Webhook

Webhook adalah semacam metode umpan balik untuk informasi pembayaran.
Saat status faktur berubah, permintaan POST dikirim ke url_callback yang ditentukan saat membuat faktur.

Tanggapan

Parameter respons

NamaDefinisi
typeJenis faktur (dompet / pembayaran)
uuiduuid pembayaran
order_idID pesanan di sistem Anda (untuk mengidentifikasi pesanan)
amountJumlah faktur
payment_amountJumlah sebenarnya yang dibayarkan oleh klien
payment_amount_usdJumlah sebenarnya yang dibayarkan oleh klien dalam USD
merchant_amountJumlah yang ditambahkan ke saldo pedagang, dengan semua komisi dikurangi.
commissionJumlah komisi Cryptomus
is_finalApakah faktur sudah final. Jika faktur sudah final, pembayarannya tidak mungkin dilakukan (karena faktur sudah lunas atau kedaluwarsa).
statusStatus pembayaranPilihan yang tersedia:confirm_checkpaidpaid_overfailwrong_amountcancelsystem_failrefund_processrefund_failrefund_paid
fromAlamat dompet pembayar
wallet_address_uuiduuid dompet statis
networkJaringan blockchain tempat pembayaran dilakukan
currencyMata uang faktur
payer_currencyMata uang yang sebenarnya digunakan klien untuk membayar
additional_dataString informasi tambahan yang Anda berikan saat membuat faktur
convertInformasi tentang mata uang yang akan dikonversi secara otomatis ke pembayaran. Konversi dilakukan dari payer_currency ke USDTKolom convert tidak akan ada jika Anda belum mengaktifkan fungsi konversi otomatis untuk payer_currency (misalnya konversi otomatis BTC ke USDT) Struktur
txidHash transaksi pada blockchain.Bidang txid tidak akan ada jika1) pembayaran dilakukan melalui p2p (Pembayar menarik dana dari akun Cryptomus-nya ke alamat yang tertera di faktur dan pembayaran dilakukan tanpa blockchain, hanya di sistem kami)2) Pembayaran tidak dilakukan3) Ada yang salah dengan pembayaran atau klien melakukan kesalahan dan kami menandainya sebagai ‘dibayar’ secara manual
signTanda tangan

Definisi

Jenis faktur (dompet / pembayaran)

Definisi

uuid pembayaran

Definisi

ID pesanan di sistem Anda (untuk mengidentifikasi pesanan)

Definisi

Jumlah faktur

Definisi

Jumlah sebenarnya yang dibayarkan oleh klien

Definisi

Jumlah sebenarnya yang dibayarkan oleh klien dalam USD

Definisi

Jumlah yang ditambahkan ke saldo pedagang, dengan semua komisi dikurangi.

Definisi

Jumlah komisi Cryptomus

Definisi

Apakah faktur sudah final. Jika faktur sudah final, pembayarannya tidak mungkin dilakukan (karena faktur sudah lunas atau kedaluwarsa).

Definisi

Status pembayaranPilihan yang tersedia:- confirm_check- paid- paid_over- fail- wrong_amount- cancel- system_fail- refund_process- refund_fail- refund_paid

Definisi

Alamat dompet pembayar

Definisi

uuid dompet statis

Definisi

Jaringan blockchain tempat pembayaran dilakukan

Definisi

Mata uang faktur

Definisi

Mata uang yang sebenarnya digunakan klien untuk membayar

Definisi

String informasi tambahan yang Anda berikan saat membuat faktur

Definisi

Informasi tentang mata uang yang akan dikonversi secara otomatis ke pembayaran. Konversi dilakukan dari payer_currency ke USDTKolom convert tidak akan ada jika Anda belum mengaktifkan fungsi konversi otomatis untuk payer_currency (misalnya konversi otomatis BTC ke USDT) Struktur

Definisi

Hash transaksi pada blockchain.Bidang txid tidak akan ada jika1) pembayaran dilakukan melalui p2p (Pembayar menarik dana dari akun Cryptomus-nya ke alamat yang tertera di faktur dan pembayaran dilakukan tanpa blockchain, hanya di sistem kami)2) Pembayaran tidak dilakukan3) Ada yang salah dengan pembayaran atau klien melakukan kesalahan dan kami menandainya sebagai ‘dibayar’ secara manual

Definisi

Tanda tangan

Struktur dari convert

NamaDefinisi
to_currencyKode mata uang yang akan dikonversikan ke pembayaran
commissionBiaya konversi
rateTingkat konversi
amountJumlah konversi dalam ke_mata uang yang ditambahkan ke saldo pedagang, dengan semua komisi dikurangi.jumlah di sini sama dengan jumlah_pedagang * tarif

Definisi

Kode mata uang yang akan dikonversikan ke pembayaran

Definisi

Biaya konversi

Definisi

Tingkat konversi

Definisi

Jumlah konversi dalam ke_mata uang yang ditambahkan ke saldo pedagang, dengan semua komisi dikurangi.jumlah di sini sama dengan jumlah_pedagang * tarif

Contoh respons


1{
2  "type": "payment",
3  "uuid": "62f88b36-a9d5-4fa6-aa26-e040c3dbf26d",
4  "order_id": "97a75bf8eda5cca41ba9d2e104840fcd",
5  "amount": "3.00000000",
6  "payment_amount": "3.00000000",
7  "payment_amount_usd": "0.23",
8  "merchant_amount": "2.94000000",
9  "commission": "0.06000000",
10  "is_final": true,
11  "status": "paid",
12  "from": "THgEWubVc8tPKXLJ4VZ5zbiiAK7AgqSeGH",
13  "wallet_address_uuid": null,
14  "network": "tron",
15  "currency": "TRX",
16  "payer_currency": "TRX",
17  "additional_data": null,
18  "convert": {
19    "to_currency": "USDT",
20    "commission": null,
21    "rate": "0.07700000",
22    "amount": "0.22638000"
23  },
24  "txid": "6f0d9c8374db57cac0d806251473de754f361c83a03cd805f74aa9da3193486b",
25  "sign": "a76c0d77f3e8e1a419b138af04ab600a"
26}
Menyalin

Verifikasi webhook

Karena dengan menerima webhook Anda merilis produk atau mengkredit saldo pengguna Anda, Anda perlu memastikan bahwa Anda menerima webhook dari Cryptomus dan bukan dari orang lain.

Kami sarankan Anda memeriksanya dengan kedua cara:

  • Gunakan daftar putih alamat IP dan izinkan permintaan ke url_callback hanya dari IP kami. Kami mengirimkan webhook dari IP 91.227.144.54.
  • Verifikasi tanda tangan di setiap webhook yang masuk ke url_callback Anda, baca selengkapnya tentang ini di bawah.

Memverifikasi tanda tangan webhook

Kunci API i Anda bersifat rahasia dan tidak seorang pun kecuali Anda dan Cryptomus boleh mengetahuinya. Jadi, saat memverifikasi tanda tangan, Anda akan yakin bahwa webhook tersebut dikirim oleh Cryptomus.

Kami membuat tanda menggunakan algoritma ini. Hash MD5 dari isi permintaan POST dikodekan dalam base64 dan digabungkan dengan kunci API Anda.

Karena tanda tangan terdapat di badan permintaan, untuk memverifikasinya, Anda perlu mengekstrak tanda dari badan respons, membuat hash dari badan dan KUNCI API Anda, lalu mencocokkannya dengan parameter tanda.

Contoh dalam php:

Untuk menerima data json yang dikirim melalui pos ke pengendali webhook Anda:


1$data = file_get_contents('php://input');
2$data = json_decode($data, true);
Menyalin

Katakanlah kita menerima webhook dengan data di ini susunan
Pertama, kita perlu mengekstrak tanda dari array:


1$sign = $data['sign'];
2unset($data['sign']);
Menyalin

Sekarang mari kita buat tanda menggunakan kunci pembayaran api kita:


1$hash = md5(base64_encode(json_encode($data, JSON_UNESCAPED_UNICODE)) . $apiPaymentKey);
Menyalin

Terakhir, kita dapat memeriksa apakah tanda yang kita hasilkan dengan kunci pembayaran API kita sama dengan tanda yang muncul di webhook.


1if (!hash_equals($hash, $sign)) {
2   return new InvalidHashException();
3}
4
5// or
6
7if ($hash !== $sign) {
8   return new InvalidHashException();
9}
Menyalin

Pada titik ini, Anda dapat yakin bahwa webhook tersebut berasal dari Cryptomus dan Anda menerima semua data dengan benar

Terdapat perbedaan saat mengodekan array data dalam PHP dan bahasa pemrograman lainnya. PHP memang menggunakan escape garis miring, sementara beberapa bahasa pemrograman lainnya tidak. Oleh karena itu, Anda mungkin mengalami ketidakcocokan tanda. Anda harus menggunakan escape garis miring dengan garis miring terbalik agar berfungsi dengan baik.

dalam php:


1//  data array
2$data = [
3    'amount' => '20',
4    'currency' => 'USDT',
5    'network' => 'tron',
6    'txid' => 'someTxidWith/Slash'
7];
8
9// json data we send to webhooks
10$data = json_encode($data, true);
11echo $data;
12// Outputs a string, slash in txid is escaped, pay attention to this.
13// we send a webhook data with all escaped slashes
14// {"amount":"20","currency":"USD","network":"btc","txid":"someTxidWith/Slash"}
Menyalin

dalam js:


1const data = {
2    amount: '20',
3    currency: 'USDT',
4    network: 'tron',
5    txid: 'someTxidWith/Slash'
6};
7
8const jsonData = JSON.stringify(data);
9console.log(jsonData);
10// {"amount":"20","currency":"USDT","network":"tron","txid":"someTxidWith/Slash"}
11// slash in txid is not escaped and you will get error checking sign.
12// Instead, you should do it like this:
13// const jsonData = JSON.stringify(data).replace(///mg, "\/");
14            
Menyalin