Payment Notification

Notifikasi ini dikirim ke URL webhook Anda setiap kali pembayaran Virtual Account berhasil.

Request dari AlnairPay

Key	Detail
URL	URL Webhook yang Anda atur di Dashboard (Settings → Webhook)
Method	POST
Content-Type	application/json

Headers

Header	Type	Description
Content-Type	String	Selalu application/json.
X-webhook-Token	String	Token Verifikasi milik akun Anda (lihat di Dashboard). Wajib dicocokkan sebelum memproses notifikasi.
X-Timestamp	String	Waktu notifikasi dibuat, format ISO 8601 UTC. Contoh: 2026-10-27T02:23:33.123Z.

note

Nama header tidak membedakan huruf besar/kecil. Sebagian framework menampilkannya sebagai x-webhook-token dan x-timestamp.

Request Body

Field	Type	Description
merchant_ref	String	Referensi transaksi milik Anda yang dikirim saat membuat Virtual Account. Gunakan field ini untuk mencocokkan notifikasi dengan invoice/pesanan di sistem Anda.
trx_id	String	ID transaksi pembayaran dari bank. Unik per pembayaran; gunakan untuk mencegah pemrosesan ganda.
va_number	String	Nomor Virtual Account yang dibayar.
amount	String	Nominal yang dibayar, berupa string dengan dua angka desimal. Contoh: "240000.00".
status	String	Status pembayaran. Untuk notifikasi ini selalu PAID.
paid_at	String	Waktu pembayaran dari bank dalam WIB (UTC+7). Format: YYYY-MM-DD HH:mm:ss. Contoh: 2026-10-27 09:23:32.

Request Body Example

{
    "merchant_ref": "INV-2026-000123",
    "trx_id": "221230BI02639274",
    "va_number": "9066003300470725",
    "amount": "240000.00",
    "status": "PAID",
    "paid_at": "2026-10-27 09:23:32"
}

CURL Example

Contoh request yang akan diterima endpoint Anda:

curl --location 'https://api.toko-anda.com/webhook/alnairpay' \
--header 'Content-Type: application/json' \
--header 'X-webhook-Token: [TOKEN-VERIFIKASI-ANDA]' \
--header 'X-Timestamp: 2026-10-27T02:23:33.123Z' \
--data '{
    "merchant_ref": "INV-2026-000123",
    "trx_id": "221230BI02639274",
    "va_number": "9066003300470725",
    "amount": "240000.00",
    "status": "PAID",
    "paid_at": "2026-10-27 09:23:32"
}'

Response dari Endpoint Anda

Endpoint Anda wajib membalas HTTP status 200 setelah notifikasi diterima dan diproses. Isi response body bebas dan tidak dibaca oleh AlnairPay, namun disarankan berupa JSON singkat.

HTTP Status dari endpoint Anda	Dianggap	Tindakan AlnairPay
200	Berhasil	Notifikasi selesai, tidak dikirim ulang.
Selain 200 (termasuk 201, 202, 204, 3xx, 4xx, 5xx)	Gagal	Notifikasi dikirim ulang (retry).
Tidak ada respons dalam 30 detik, koneksi ditolak, atau error SSL	Gagal	Notifikasi dikirim ulang (retry).

Response Example (Success)

{
    "success": true
}

warning

Hanya HTTP 200 yang dianggap berhasil. Status sukses lain seperti 201 Created atau 204 No Content tetap dianggap gagal dan akan memicu pengiriman ulang.

Retry

Jika endpoint Anda tidak membalas HTTP 200, AlnairPay mengirim ulang notifikasi yang sama persis (body identik) dengan jeda yang makin panjang:

Percobaan	Waktu setelah percobaan sebelumnya
1	Segera setelah pembayaran dikonfirmasi
2	± 20 detik
3	± 40 detik
4	± 80 detik
5	± 160 detik

Setelah 5 percobaan gagal (sekitar 5 menit setelah pembayaran), notifikasi tidak dikirim lagi. Status pembayaran tetap tercatat PAID di AlnairPay dan dapat dilihat melalui Dashboard atau endpoint cek status VA.

info

Karena adanya retry, endpoint Anda bisa menerima notifikasi yang sama lebih dari sekali, misalnya bila sistem Anda sudah memproses pembayaran tetapi balasannya terlambat (timeout). Lihat Idempotensi untuk cara menanganinya.