Integrasi Backend•Webhook Architecture
Arsitektur Asynchronous Webhook
Layanan Transaction Converter Manager mengirimkan HTTP POST secara **asynchronous** ke alamat URL yang didaftarkan merchant (UrlCallback) sesaat setelah pemrosesan transaksi Payment atau Refund selesai dieksekusi di backend core Qoin.
7 Tahapan Alur Kerja Callback
| Tahap | Arah | Proses & Keterangan |
|---|---|---|
| 1. Inisiasi | Merchant $\rightarrow$ Gateway | Merchant menginisiasi transaksi (menyertakan field UrlCallback). |
| 2. Immediate Response | Gateway $\rightarrow$ Merchant | Gateway segera merespons HTTP 200 / 201 menandakan transaksi diterima untuk diproses. |
| 3. Background Execution | Gateway $\leftrightarrow$ Core | Debit / Topup / Settlement diproses di background hingga memperoleh hasil final (Sukses/Gagal). |
| 4. Signature Generation | Gateway | Gateway menandatangani JSON payload menggunakan algoritma RSA-SHA256 dengan RSA Private Key. |
| 5. Callback Delivery | Gateway $\rightarrow$ Merchant | HTTP POST dikirim ke {UrlCallback} dengan JSON body + header Signature. |
| 6. Acknowledgement | Merchant $\rightarrow$ Gateway | Server merchant membalas HTTP 200 OK dalam batas waktu maksimal 30 detik. |
| 7. Retry (Jika Perlu) | Gateway $\rightarrow$ Merchant | Jika timeout atau non-2xx, gateway mengulang pengiriman maksimal 3 kali dengan jeda 5 detik. |
Ketentuan Keamanan Jaringan & Validasi URL
SSRF Protection
Gateway menerapkan proteksi ketat SSRF (*Server-Side Request Forgery*). Nilai
UrlCallback akan divalidasi:- URL wajib menggunakan protokol aman
https://dengan sertifikat SSL valid. - Alamat IP privat (seperti
127.0.0.1,localhost,192.168.x.x,10.x.x.x) akan ditolak secara otomatis oleh gateway.
Sifat Asynchronous Callback
Merchant tidak perlu menahan request inisiasi awal pengguna hingga proses bisnis perbankan selesai. Status final transaksi akan selalu dikirimkan melalui webhook asynchronous ini.