Integrasi Backend•Reliability & Architecture
Kebijakan Retry, Timeout & Idempotensi
Dalam arsitektur *event-driven* perbankan, pengiriman callback dapat mengalami kendala fluktuasi jaringan. Gateway Qoin menerapkan kebijakan retry otomatis untuk menjamin keandalan pengantaran data (*at-least-once delivery*).
Kebijakan Retry Gateway
| Parameter | Nilai / Ketentuan |
|---|---|
| Batas Waktu (Timeout) | Maksimal 30 detik per percobaan HTTP POST. |
| Jumlah Percobaan (Attempts) | Maksimal 3 kali percobaan (Attempt 1, 2, dan 3). |
| Interval Jeda Retry | Jeda 5 detik sebelum melakukan percobaan berikutnya jika menerima non-2xx atau timeout. |
| Kriteria Sukses | HTTP Status Code 2xx (terutama 200 OK). Retry langsung dihentikan. |
Penerapan Idempotensi di Sisi Merchant
Karena sistem menggunakan prinsip *at-least-once delivery*, ada kemungkinan endpoint merchant menerima payload callback yang sama lebih dari satu kali (misal akibat koneksi terputus saat respon 200 OK sedang dikirimkan kembali ke gateway).
Pola Idempotensi yang Wajib Diterapkan
- Gunakan kombinasi
OrderNodanReferenceNosebagai *Idempotency Key* unik di database merchant. - Saat menerima callback, periksa apakah pesanan dengan
OrderNotersebut sudah berstatus selesai (*PAID* / *REFUNDED*). - Jika pesanan sudah berstatus final, jangan mengeksekusi ulang penambahan saldo atau pengiriman barang dua kali. Cukup segera balas kembali dengan HTTP 200 OK.
- Jika pesanan masih pending, verifikasi signature terlebih dahulu $\rightarrow$ ubah status menjadi sukses $\rightarrow$ jalankan fulfilment.
Respon Cepat Menggunakan Background Worker
Pemrosesan berat seperti pengiriman notifikasi email, cetak struk fisik, atau sinkronisasi ERP sebaiknya dialihkan ke asynchronous background worker (misal Redis queue, RabbitMQ, Kafka, atau Celery). Endpoint webhook harus segera membalas
HTTP 200 OK dalam waktu kurang dari 2 detik agar tidak terkena timeout 30 detik gateway.