Webhook URL
Ikhtisar
Fitur ini mengantarkan data tagihan yang dibayar ke server merchant. Fitur ini ada agar toko merchant dapat memproses pembayaran secara otomatis dan menyerahkan produk atau jasa kepada pembeli Anda.
Webhook URL diatur satu per satu untuk setiap proyek dan mengarah ke skrip penangan pembayaran di dalam toko merchant. Alamatnya harus memakai HTTPS dan nama domain: alamat IP tidak diterima, dan sertifikat diverifikasi pada setiap pengiriman.
Setiap kali status tagihan berubah menjadi Dibayar (Paid), layanan mengirim permintaan POST ke URL ini dalam format berikut:
{
"wallet":{
"id":"47aa71e2-07a0-482e-9172-7114d7376ba0",
"name":"usdt-tron",
"blockchain":"tron",
"cryptocurrency":"usdt",
"address":"TKbstUwMzLrfTAGL4erYb7gc7ghmHQ9zG7"
},
"project":{
"id":"9deea1e2-0c08-41a3-bdc2-a34eada3892d",
"name":"My project",
"commissionPayer":"seller",
"commissionRate":1
},
"invoice":{
"id":"a4c9e2ee-9a03-43e5-a1a1-00caf679d16a",
"uid":"AFhygKX21ecd",
"createDatetime":"2024-02-26 13:29:24",
"timeToPayDatetime":"2024-02-27 01:29:24",
"commissionFiatUSD":0.05,
"amountFiatUSD":5.02,
"amountFiat":5,
"calcAmountFiat":5.02,
"currencyFiat":"USD",
"description":null,
"serviceData":null,
"status":"paid"
},
"payment":{
"id":"f986ad8d-2298-473d-982a-efbc817b975d",
"amount":5.02,
"hash":"74763b65e43bcc9492a6ce9a7f26fbfdbd7635aecd3454420b5e9534cba50ee6",
"transactionDatetime":"2024-02-26 13:32:57"
}
}
Notifikasi dikirim pada setiap transisi ke Dibayar—baik saat layanan menemukan pembayaran secara otomatis maupun saat merchant mencocokkan pembayaran dengan tagihan secara manual.
Parameter permintaan
| Parameter | Deskripsi |
|---|---|
wallet.id | ID dompet dalam format UUID |
wallet.name | Nama dompet |
wallet.blockchain | Blockchain dompet kripto |
wallet.cryptocurrency | Mata uang kripto dompet |
wallet.address | Alamat dompet kripto |
project.id | ID proyek dalam format UUID |
project.name | Nama proyek |
project.commissionPayer | Siapa yang menanggung biaya layanan |
project.commissionRate | Tarif dalam % |
invoice.id | ID tagihan dalam format UUID |
invoice.uid | ID tagihan (untuk pembeli) |
invoice.createDatetime | Tanggal dan waktu pembuatan tagihan (UTC) |
invoice.timeToPayDatetime | Tanggal dan waktu hingga kapan tagihan berlaku untuk pembeli (UTC). Pencarian pembayaran berlanjut 1 jam lagi setelah batas ini—untuk mengantisipasi jaringan lambat. Jadi notifikasi bisa tiba untuk tagihan yang sudah tampil sebagai kedaluwarsa |
invoice.commissionFiatUSD | Jumlah biaya layanan. Dihitung dari jumlah invoice.amountFiatUSD |
invoice.amountFiatUSD | Jumlah dalam USD. Saat pembuatan tagihan dihitung dari invoice.amountFiat berdasarkan kurs terkini. Pada saat pembayaran ditimpa dengan jumlah yang benar-benar diterima, dikonversi ke USD dengan kurs saat itu. Biaya di invoice.commissionFiatUSD juga dihitung ulang darinya |
invoice.amountFiat | Jumlah asli tagihan dalam mata uang fiat. Tidak berubah |
invoice.calcAmountFiat | Jumlah hasil perhitungan dalam mata uang invoice.currencyFiat menurut kurs kripto pada saat pembayaran. Nilainya bisa berbeda dari invoice.amountFiat karena pembeli mungkin membayar tagihan beberapa waktu setelah pembuatan, bukan seketika. Selama waktu itu, kurs kripto terhadap invoice.currencyFiat bisa bergerak ke arah mana pun |
invoice.currencyFiat | Mata uang fiat |
invoice.description | Deskripsi yang diisi saat pembuatan tagihan |
invoice.serviceData | Data layanan yang diisi saat pembuatan tagihan |
invoice.status | Status tagihan |
payment.id | ID pembayaran dalam format UUID |
payment.amount | Jumlah pembayaran dalam mata uang kripto |
payment.hash | Hash transaksi on-chain |
payment.transactionDatetime | Tanggal dan waktu transaksi on-chain (UTC) |
Tanda tangan notifikasi
Setiap permintaan ditandatangani dengan kunci rahasia webhook. Tanda tangan berjalan di header X-Timestamp dan X-Signature dan memungkinkan Anda memastikan notifikasi datang dari layanan, bukan dari pihak luar yang mengetahui alamat penangan Anda.
Verifikasi tanda tangan sebelum memproses pesanan. Mekanisme dan contoh siap pakainya ada di Verifikasi tanda tangan webhook.
Rekomendasi penanganan
Jangan menolak notifikasi karena batas waktu pembayaran sudah lewat. Pemeriksaan seperti “tagihan kedaluwarsa, berarti pembayarannya tidak sah” tampak logis tetapi memangkas sebagian pembayaran nyata: di jaringan lambat transaksi bisa terkonfirmasi setelah batas waktu, dan merchant dapat mencocokkan pembayaran dengan tagihan kedaluwarsa secara manual. Notifikasi itu sendiri sudah mengonfirmasi pembayaran.
Verifikasi jumlah terhadap field aslinya invoice.amountFiat. Inilah jumlah tagihan sebagaimana diterbitkan, dan nilainya tidak berubah. Field amountFiatUSD mencerminkan jumlah yang benar-benar diterima dan bisa berbeda dari yang diterbitkan—baik karena pergerakan kurs maupun karena pencocokan pembayaran manual.
Urai jumlah sebagai angka. Nol di belakang dibuang: jumlah 10.00 tiba sebagai 10; format di sisi Anda untuk ditampilkan. Jumlah di bawah 0.0001 tiba dalam notasi eksponensial, misalnya 1.0e-6—penguraian JSON standar mengembalikan angka yang benar; hanya penguraian string manual yang rusak.
Tangani notifikasi secara idempoten. Notifikasi yang sama bisa tiba lagi—misalnya, jika skrip Anda berhasil memproses pembayaran tetapi mengembalikan kode non-2xx. Sebelum mengirim pesanan, periksa apakah invoice.id ini sudah pernah diproses.
Escape nilai saat keluaran. Field invoice.description dan invoice.serviceData kembali persis seperti yang dikirim merchant. Jika Anda merendernya dalam HTML, lakukan escape di sisi Anda.
Jadwal pengiriman
Server di Webhook URL harus membalas dengan kode HTTP 2xx. Kode lain, waktu habis, atau koneksi terputus dihitung sebagai pengiriman gagal.
Pengalihan tidak diikuti: respons 301 atau 302 adalah pengiriman gagal, bukan lompatan ke alamat baru. Pasang alamat akhir penangan.
Koneksi diberi waktu 5 detik, seluruh permintaan 10 detik. Jika penangan tidak selesai dalam waktu itu, pengiriman dihitung gagal.
Setelah pengiriman gagal, layanan melakukan percobaan ulang dengan jadwal berikut:
- 5 menit setelah pengiriman gagal terakhir
- Setelah 15 menit
- Setelah 30 menit
- Setelah 1 jam
- Setelah 3 jam
- Setelah 6 jam
- Setelah 12 jam
- Setelah 24 jam
Setelah itu, upaya pengiriman berhenti.
Menonaktifkan Webhook URL
Kadang-kadang skrip webhook toko memproses pembayaran dengan benar tetapi mengembalikan kode HTTP non-2xx. Ini menyebabkan percobaan ulang yang sering dari server kami sesuai jadwal di atas, dan membebani server kami maupun server Anda.
Untuk mencegah kasus seperti itu, kami punya mekanisme yang menonaktifkan Webhook URL di proyek. Agar terhindar darinya, lakukan langkah-langkah berikut:
- Ubah kode penangan webhook Anda agar mengembalikan kode 2xx, biasanya 200, saat pembayaran berhasil diproses. Uji dengan emulator apa pun, misalnya Postman.
- Hubungi dukungan teknis untuk membetulkan pengaturan.
- Aktifkan kembali Webhook URL di pengaturan proyek dan simpan proyek.