FQrisDocs
SitusStatus
Panduan

Sandbox

Uji alur pembayaran sampai webhook tanpa uang sungguhan.

3 menit bacaDiperbarui 29 Okt 2026

Mode uji

Pakai API key fq_test_…. Payment, event, dan webhook mode uji terpisah total dari live. Kamu tidak butuh Listener atau QRIS terverifikasi: payment uji boleh memakai QRIS source yang masih unverified.

Checkout payment uji berada di path /test/p/… dan berlabel "MODE UJI — jangan dibayar". Langganan dan tagihan tidak berlaku untuk mode uji.

Jangan bayar QR uji
Uang sungguhan yang dibayar ke QR uji tidak mencocokkan payment uji, karena notifikasi dari HP hanya dicocokkan dengan payment live. Notifikasinya masuk ke Rekonsiliasi live sebagai unmatched, jadi tidak hilang.

Simulasikan pembayaran

Panggil POST /v1/sandbox/payments/{id}/simulate dengan key test (scope payments:write). Body-nya { "result": … }, dan respons 200 berisi objek Payment setelah simulasi.

  1. 1
    paid Payment menjadi paid dengan confirmation_method: sandbox_simulation, dan webhook payment.paid terkirim.
  2. 2
    expired Payment pending menjadi expired seketika, dan webhook payment.expired terkirim. expires_at digeser ke 1 detik lalu supaya pembayaran berikutnya dihitung terlambat.
  3. 3
    paid_late Payment dikedaluwarsakan dulu lalu dibayar: hasilnya paid dengan paid_late: true. Pakai ini untuk menguji kredit setelah kedaluwarsa.
simulasi-bayar
1import FQris from '@fqris/node';
2const fqris = new FQris(process.env.FQRIS_KEY);
3
4const payment = await fqris.sandbox.simulatePayment('pay_01JA2Z3K8M', {
5 result: 'paid',
6});
7console.log(payment.status);

Hanya tiga nilai result itu yang diterima; nilai lain dijawab 400 INVALID_PARAMETER. Key live dijawab 404 RESOURCE_NOT_FOUND. Payment yang sudah paid, atau yang masa tenggangnya sudah habis, dijawab 409 INVALID_STATE_TRANSITION.

Simulasikan notifikasi Listener

POST /v1/sandbox/devices/simulate-notification mengirim teks notifikasi tiruan lewat parser dan pencocokan yang sama dengan HP Listener, tetapi hanya terhadap payment mode uji. Cocok untuk menguji alur dari notifikasi sampai webhook.

Body-nya source_id (id QRIS source, qrs_…), text (isi notifikasi, 1–4000 karakter), dan title (opsional, maksimal 500 karakter). Responsnya memuat status pemrosesan, parsed_amount, matched_payment_id, dan labels. Pakai source_id milik usahamu sendiri; id lain dijawab 404.

Dari checkout dan dashboard

Di halaman checkout mode uji ada tombol "Simulasikan bayar". Ia memanggil POST /public/checkout/{token}/simulate, setara dengan hasil paid. Untuk payment live endpoint ini menjawab 404.

Di dashboard, tab Sandbox pada halaman Developer punya "Buat payment test" dan "Simulasikan bayar". Panel itu menampilkan tahapnya: notifikasi tiruan, parser dan match, status paid, lalu webhook uji. Hanya Owner dan Developer yang bisa memakainya.

Webhook uji ikut mode
Event mode uji hanya dikirim ke endpoint webhook mode uji, dengan secret uji. Daftarkan endpoint di mode uji dulu supaya payment.paid dari simulasi sampai ke servermu.

Batas sandbox

  1. 1
    Rate limit Bawaannya 120 request per menit per API key test (live 300). POST /v1/payments tetap 60 per menit.
  2. 2
    Retensi data Data uji dihapus otomatis setelah 30 hari oleh pembersihan harian.
  3. 3
    Key live Endpoint simulasi hanya menerima key test. Key live dijawab 404.
  4. 4
    Pembayaran ganda Pembayaran ganda (payment.overpaid) tidak bisa disimulasikan. Hasil simulasi hanya paid, expired, dan paid_late.
Apakah halaman ini membantu?