KiPaydocs
Dokumentasi/Konsep

KONSEP

Uji lifecycle penuh sebelum menerima dana nyata

Sandbox menggunakan kontrak transaksi yang sama dengan production, ditambah endpoint simulasi untuk menguji perubahan status dengan aman.

5 menit Diperbarui 29 Agustus 2026
PERBANDINGAN ENVIRONMENTKontrak sama, sumber konfirmasi berbeda.
Perbandingan sandbox dan productionSandbox dan production memakai struktur request, resource transaksi, renderer QR, dan webhook handler yang sama. Hanya sandbox yang memiliki endpoint simulate. Production menerima konfirmasi dari jaringan QRIS.SAMAKAN KONTRAK SEBELUM GO LIVESANDBOXPRODUCTIONkonfirmasi terkendalikonfirmasi jaringan nyatastruktur requestkontrak samafield transaksikontrak samarender QRkontrak samawebhook handlerkontrak samaPOST /simulate mengubah statusjaringan QRIS mengubah status
01

Dua environment, satu pola integrasi

Mode project disalin ke transaksi saat transaksi dibuat. ID transaksi sandbox menggunakan prefiks SBX, sedangkan ID transaksi production menggunakan prefiks QRIS. Jangan mencampur ID, credential, atau data dari kedua environment.

PerilakuSandboxProduction
Dana nyataTidakYa
Simulasi paidTersediaDitolak
WebhookDapat diujiAktif untuk pembayaran nyata
Prefiks transaksiSBXQRIS
02

Kasus yang wajib diuji

  • Transaksi berubah dari pending menjadi paid
  • Transaksi berubah menjadi expired tanpa pembayaran
  • Webhook yang sama diterima lebih dari sekali
  • Webhook tiba setelah polling mendeteksi perubahan
  • trx_id tidak ditemukan
  • API key salah atau project dinonaktifkan
03

Checklist sebelum production

  1. 01
    Pisahkan konfigurasi

    Gunakan environment variable yang berbeda untuk credential sandbox dan production, termasuk webhook secret masing-masing.

  2. 02
    Amankan webhook

    Gunakan HTTPS, verifikasi X-Webhook-Signature, batasi ukuran payload, dan tetap baca ulang status transaksi dari backend.

  3. 03
    Buat operasi idempotent

    Pemrosesan event paid untuk kedua kalinya tidak boleh memenuhi order lagi.

  4. 04
    Siapkan observability

    Catat request, trx_id, event, dan hasil pemenuhan order tanpa merekam API key atau webhook secret.

04

Signature dan retry webhook

Setiap webhook ditandatangani dan dicoba ulang otomatis

Verifikasi X-Webhook-Signature sebelum memproses payload — lihat panduan "Terima webhook". Kalau endpoint Anda gagal merespons 2xx, KiPay mencoba ulang hingga 6 kali dengan jeda meningkat (~10 detik sampai ~160 detik), lalu berhenti kalau tetap gagal. Perilaku retry ini masih bisa disesuaikan seiring waktu — jangan hardcode jumlah atau jeda persisnya, cukup pastikan handler Anda aman menerima event yang sama berkali-kali.