KiPaydocs
Dokumentasi/API Reference

API REFERENCE

Event webhook

Payload yang dikirim KiPay ke webhook URL project ketika status transaksi berubah atau tes koneksi dijalankan.

Referensi Diperbarui 29 Agustus 2026
PENGIRIMAN IDEMPOTENTPengiriman berulang tetap menghasilkan satu pemenuhan order.
Pengiriman webhook yang idempotentPengiriman pertama dan duplikat masuk ke dedupe gate yang menggunakan trx_id. Handler memberi response dengan cepat. Satu verifikasi di background menghasilkan satu pemenuhan order. Duplikat tidak menghasilkan pemenuhan kedua.BANYAK PENGIRIMAN, SATU DAMPAKPENGIRIMAN 01transaction.paidtrx_id: VG57V5PENGIRIMAN 02event yang samatrx_id: VG57V5DEDUPEberdasarkan trx_idcatat sekalipertama diterimasudah diprosesPENUHI SEKALIsetelah verifikasi APIBalas cepat. Verifikasi dan penuhi order di background.
01

Header request

HeaderKeterangan
Content-Typeapplication/json
User-AgentKiPay-Webhook/1.0
X-Webhook-EventSama dengan field event pada payload
X-Webhook-DeliveryID delivery unik dan stabil — sama persis pada percobaan ulang untuk event yang sama
X-Webhook-TimestampWaktu pengiriman (ISO 8601), ikut ditandatangani
X-Webhook-Signaturesha256=<hex> — HMAC-SHA256("{timestamp}.{deliveryId}.{rawBody}", webhook_secret). Lihat panduan "Terima webhook" untuk cara verifikasi.
02

Payload

net_amount hanya muncul di sini dan di dashboard merchant — tidak ada di response API checkout publik (lihat POST /transactions).

transaction-paid.json
JSON
{
  "event": "transaction.paid",
  "sent_at": "2026-08-26T06:35:14Z",
  "transaction": {
    "trx_id": "SBX-20260825-VG57V5",
    "mode": "sandbox",
    "requested_amount": 285000,
    "unique_code": 215,
    "amount": 285215,
    "fee_amount": 2925,
    "net_amount": 282290,
    "fee_bearer": "merchant",
    "status": "paid",
    "provider": "shopeepay",
    "note": "order_nusa_2048",
    "matched_at": "2026-08-26 06:35:14",
    "created_at": "2026-08-26 06:35:08",
    "expires_at": "2026-08-26 06:50:08"
  }
}
03

Jenis event

EventMakna
transaction.paidTransaksi berubah menjadi paid
transaction.expiredTransaksi melewati expires_at
webhook.testTes koneksi dari project
04

Kontrak keamanan

Setiap payload ditandatangani — selalu verifikasi

Hitung ulang HMAC-SHA256 atas "{timestamp}.{deliveryId}.{rawBody}" memakai webhook secret project, bandingkan dengan X-Webhook-Signature memakai constant-time comparison, dan tolak timestamp yang sudah terlalu lama (replay window disarankan 5 menit). SDK kipay-node menyediakan verifyWebhookSignature() untuk ini. Signature yang valid membuktikan payload asli dari KiPay — tetap baca ulang status transaksi lewat API sebelum memenuhi order.

05

Retry saat gagal

Kalau endpoint Anda tidak merespons 2xx (atau timeout), KiPay mencoba ulang hingga 6 kali dengan jeda meningkat (~10 detik sampai ~160 detik), lalu berhenti. X-Webhook-Delivery tetap sama di setiap percobaan ulang untuk event yang sama.