FQrisDocs
SitusStatus
Panduan

Webhook

Terima notifikasi bertanda tangan setiap kali status payment berubah, lalu kredit pesanan secara aman dan idempoten.

8 menit bacaDiperbarui 17 Okt 2026

Event yang dikirim

Default endpoint menerima semua payment.* kecuali payment.created. Yang paling penting: payment.paid, payment.expired, payment.reversed, dan payment.overpaid.

Verifikasi signature

Header FQris-Signature berisi t (timestamp) dan v1 = HMAC-SHA256(secret, "{t}.{raw_body}"). Verifikasi dengan raw body sebelum di-parse, bandingkan constant-time, dan tolak t lebih dari 5 menit.

webhook-handler
1app.post('/webhooks/fqris', express.raw({ type: '*/*' }), async (req, res) => {
2 const sig = req.headers['fqris-signature'];
3 // 1. Verifikasi dengan raw body + toleransi 5 menit
4 const event = fqris.webhooks.constructEvent(req.body, sig, process.env.WHSEC);
5 // 2. Ambil ulang status sebelum mengkredit
6 const p = await fqris.payments.retrieveAndAssertPaid(event.data.object.id);
7 await creditCoinsOnce(p.id, p.metadata.user_id);
8 res.sendStatus(200);
9});
Jangan percaya return_url
Kredit koin atau tandai pesanan lunas hanya dari webhook terverifikasi plus GET /v1/payments/{id}, di dalam transaksi DB dengan kunci unik payment_id.

Retry & pengiriman

Respons 2xx dianggap sukses; redirect dihitung gagal. Timeout 10 detik per percobaan, 8 percobaan dengan jitter ±10%.

#1segera#230 dtk#32 mnt#410 mnt#530 mnt#61 jam#73 jam#86 jam
Urutan tidak dijamin
Gunakan data.object.status dan updated_at, bukan urutan kedatangan event. Proses idempoten berdasarkan event.id.

Kasus khusus

  1. 1
    paid_late Pembayaran setelah kedaluwarsa. Pesanan mungkin sudah kamu batalkan: kredit atau refund sesuai kebijakanmu.
  2. 2
    payment.reversed Konfirmasi manual dibatalkan Owner dalam 24 jam. Tarik kembali koin yang sudah dikredit.
  3. 3
    payment.overpaid Pembeli membayar dua kali QR yang sama. Status tidak berubah otomatis; tim mendapat notifikasi.
Apakah halaman ini membantu?