Dokumentasi API NawaPay

NPY Engine adalah infrastruktur bank digital dan multi payment gateway. Dokumentasi ini menjelaskan cara mengintegrasikan sistem kamu dengan API publik merchant: membuat pembayaran, memantau statusnya, mengembalikan dana, membaca saldo, dan menerima notifikasi peristiwa.

Tahap pengembangan. Seluruh contoh di halaman ini berjalan di lingkungan sandbox. NPY Engine belum berizin sebagai penyelenggara jasa pembayaran dan belum memproses transaksi uang sungguhan. Sebagian layanan mungkin belum merespons; kondisi terkini dapat dilihat di status.nawapay.co.id.

Autentikasi

Tanda tangan HMAC, jendela waktu, dan contoh dalam enam bahasa.

Idempotensi

Kenapa setiap permintaan tulis membawa kunci, dan apa arti 409.

Referensi endpoint

Payments, refunds, balances, settlements, disputes.

Dasar

Seluruh API berada di bawah satu base URL dan satu versi mayor. Format pertukaran data adalah JSON berpengodean UTF-8. Semua nominal uang dikirim dan diterima sebagai bilangan bulat satuan terkecil — tidak pernah sebagai bilangan pecahan.

Base URL	https://api.nawapay.co.id/v1
Format	JSON (UTF-8), Content-Type: application/json
Waktu	RFC 3339 dengan zona UTC, contoh 2026-08-04T02:15:30Z
Nominal	Bilangan bulat satuan terkecil pada bidang *_minor
Autentikasi	Bearer client_id + tanda tangan HMAC-SHA256

Mulai cepat

Empat langkah dari nol sampai pembayaran pertama berhasil dibuat di sandbox.

1. Buat akun merchant

Daftar melalui merchant.nawapay.co.id. Lengkapi data badan usaha, penanggung jawab teknis, dan alamat webhook. Akun sandbox aktif segera setelah surel diverifikasi; akun produksi menunggu peninjauan.

2. Ambil client_id dan secret

Pada menu Kunci API, buat sepasang kredensial. Kamu akan menerima:

client_id — pengenal publik, dikirim pada header Authorization. Berawalan ak_test_ di sandbox dan ak_live_ di produksi.
secret — kunci rahasia untuk membentuk tanda tangan. Hanya ditampilkan satu kali. Simpan di brankas rahasia, bukan di repositori kode.

Secret tidak pernah dikirim dalam permintaan. Yang dikirim adalah hasil tanda tangan. Bila kamu pernah menempelkan secret ke berkas yang dapat dibaca publik, cabut kunci itu dan buat yang baru.

3. Bentuk tanda tangan

Setiap permintaan membawa tiga header keamanan. Rinciannya ada di halaman Autentikasi.

Header	Isi
Authorization	Bearer <client_id>
X-Timestamp	Waktu Unix dalam detik. Toleransi 300 detik.
X-Signature	hmac_sha256(secret, timestamp + "." + body) dalam heksadesimal huruf kecil.
Idempotency-Key	Wajib pada semua permintaan yang menulis. Lihat Idempotensi.

4. Panggilan pertama

Membuat satu pembayaran QRIS senilai Rp150.000 di sandbox:

CLIENT_ID="ak_test_9f2c1d7b4a05"
SECRET="sk_test_4d8e1f0a7c93b25e6a1f0c84d7b3e592"
TS=$(date +%s)
BODY='{"amount_minor":150000,"currency":"IDR","payment_method":"qris","reference_id":"ORD-10427"}'
SIG=$(printf '%s' "$TS.$BODY" | openssl dgst -sha256 -hmac "$SECRET" -r | cut -d' ' -f1)

curl -sS -X POST https://api.nawapay.co.id/v1/payments \
  -H "Authorization: Bearer $CLIENT_ID" \
  -H "X-Timestamp: $TS" \
  -H "X-Signature: $SIG" \
  -H "Idempotency-Key: 4f8c1f6e-2c1a-4d5b-9d61-3f0b7a2c9e14" \
  -H "Content-Type: application/json" \
  -d "$BODY"

Respons 201 Created:

{
  "reference": "pay_01J9Q4M2T7K3XW",
  "status": "pending",
  "amount_minor": 150000,
  "currency": "IDR",
  "exponent": 0,
  "fee_minor": 2100,
  "net_minor": 147900,
  "payment_method": "qris",
  "reference_id": "ORD-10427",
  "gateway_code": "qris_sandbox",
  "environment": "sandbox",
  "expires_at": "2026-08-04T02:45:30Z",
  "instructions": {
    "type": "qr_string",
    "value": "00020101021226..."
  },
  "created_at": "2026-08-04T02:15:30Z"
}

Pembayaran dimulai dengan status pending. Status akhir sampai kepada kamu melalui webhook; jangan mengandalkan polling sebagai mekanisme utama.

Lingkungan & konvensi

Dua lingkungan yang tidak pernah bercampur

Setiap entitas uang menyimpan bidang environment secara eksplisit. Kredensial sandbox tidak dapat menyentuh data produksi, dan sebaliknya.

Lingkungan	Awalan kunci	Perilaku
sandbox	ak_test_ / sk_test_	Diproses simulator acquirer internal. Tidak ada uang sungguhan. Status dapat dipicu manual dari portal merchant.
production	ak_live_ / sk_live_	Diproses penyedia sungguhan. Belum aktif — menunggu penyelesaian tahap pengembangan dan proses perizinan.

Paginasi

Endpoint daftar memakai kursor. Kirim limit (maksimum 100, bawaan 25) dan starting_after berisi identitas objek terakhir yang sudah kamu terima.

GET /v1/settlements?limit=50&starting_after=set_01J9Q0M8R2

{
  "data": [ /* … */ ],
  "has_more": true,
  "next_cursor": "set_01J9Q7X4B1"
}

Pembatasan laju

Batas bawaan adalah 100 permintaan per menit per client_id. Setiap respons membawa header sisa kuota; bila kuota habis, API menjawab 429 beserta Retry-After.

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 84
X-RateLimit-Reset: 1785200400
Retry-After: 17

Identitas objek

reference — identitas pembayaran yang diterbitkan NPY Engine, contoh pay_01J9Q4M2T7K3XW.
reference_id — identitas milik sistem kamu, contoh nomor pesanan. Wajib unik per merchant.
request_id — identitas satu permintaan HTTP, dikembalikan pada setiap respons dan setiap galat. Sertakan saat melapor ke dukungan.