Callback reliability

Webhook idempotent dan callback final merchant harus diperlakukan sebagai kontrak, bukan sekadar notifikasi.

APIGOQR dirancang supaya final status pembayaran QRIS tidak dobel, tidak race, dan tidak bergantung pada polling merchant. Fokus utamanya adalah validasi webhook, finalisasi transaksi yang aman, lalu callback final ke callback_url merchant.

Panduan publik

Konten yang dibuat untuk membantu merchant memahami kontrak integrasi

Halaman ini ditujukan untuk merchant, tim operasional, dan tim integrasi yang ingin membaca satu topik secara lebih fokus tanpa harus masuk ke dashboard.

Idempotency mencegah transaksi yang sama difinalisasi dua kali

External API bisa saja mengirim webhook ulang. Karena itu finalisasi transaksi berdasarkan trx_id harus atomik dan hanya boleh berhasil saat status sebelumnya masih pending.

Pendekatan ini menghindari kasus pending balance bertambah dua kali, callback merchant dikirim berulang, atau histori transaksi menjadi tidak konsisten.

  • Finalisasi berbasis trx_id
  • Status hanya bisa berpindah sekali dari pending ke status final
  • Race condition dibatasi di layer repository dan service

Callback merchant dikirim setelah status final tervalidasi

Merchant tidak menerima callback sementara atau status spekulatif. Callback baru dikirim setelah project menerima dan memproses status final success, failed, atau expired dari vendor.

Dengan pola ini, merchant website dapat memperlakukan callback sebagai sinyal update order yang final.

  • Callback hanya setelah status final
  • Support untuk success, failed, dan expired
  • Callback readiness bisa diuji dari halaman testing

Observability tetap penting untuk tim merchant

Project menyimpan snapshot final di cache dan menulis log untuk webhook masuk, callback keluar, dan error. Ini memudahkan tim merchant saat perlu rekonsiliasi atau investigasi integrasi.

Kalau callback merchant tidak merespons HTTP 200 dengan body success, tim merchant bisa mendeteksinya lebih cepat lewat route testing.

  • Cache snapshot per trx_id
  • Logging untuk webhook, callback, dan error
  • Testing callback readiness untuk server merchant

FAQ

Pertanyaan yang sering muncul di topik ini

Mengapa callback merchant tidak dikirim segera saat QR dibuat?

Karena callback merchant dipakai untuk status final transaksi, bukan untuk status pending saat QR baru dibuat.

Mengapa idempotency penting?

Tanpa idempotency, webhook dobel bisa menyebabkan pending balance, histori, atau callback merchant diproses lebih dari sekali.