Webhook
Webhook là một phương pháp phản hồi thông tin thanh toán.
Khi trạng thái hóa đơn thay đổi, yêu cầu POST sẽ được gửi đến url_callback được chỉ định khi tạo hóa đơn.
Khi trạng thái hóa đơn thay đổi, yêu cầu POST sẽ được gửi đến url_callback được chỉ định khi tạo hóa đơn.
Phản ứng
Các thông số phản hồi
| Tên | Sự định nghĩa |
|---|---|
| type | Loại hóa đơn (ví / thanh toán) |
| uuid | uuid của thanh toán |
| order_id | ID đơn hàng trong hệ thống của bạn (để xác định đơn hàng) |
| amount | Số tiền của hóa đơn |
| payment_amount | Số tiền thực tế khách hàng đã trả |
| payment_amount_usd | Số tiền thực tế khách hàng đã thanh toán bằng USD |
| merchant_amount | Số tiền được thêm vào số dư của người bán, sau khi đã trừ đi tất cả hoa hồng. |
| commission | Số tiền hoa hồng của Cryptomus |
| is_final | Hóa đơn đã được hoàn tất hay chưa. Khi hóa đơn đã được hoàn tất, không thể thanh toán hóa đơn (hóa đơn đã được thanh toán hoặc đã hết hạn). |
| status | Trạng thái thanh toánCác tùy chọn có sẵn:• confirm_check• paid• paid_over• fail• wrong_amount• cancel• system_fail• refund_process• refund_fail• refund_paid |
| from | Địa chỉ ví của người trả tiền |
| wallet_address_uuid | uuid của ví tĩnh |
| network | Mạng blockchain nơi thanh toán được thực hiện |
| currency | Tiền tệ hóa đơn |
| payer_currency | Tiền tệ mà khách hàng thực sự đã thanh toán |
| additional_data | Chuỗi thông tin bổ sung mà bạn đã cung cấp khi tạo hóa đơn |
| convert | Thông tin về loại tiền tệ mà khoản thanh toán sẽ được tự động chuyển đổi. Việc chuyển đổi được thực hiện từ payer_currency sang USDTTrường chuyển đổi sẽ không tồn tại nếu bạn chưa bật chức năng chuyển đổi tự động cho payer_currency (ví dụ: tự động chuyển đổi BTC sang USDT) Kết cấu |
| txid | Băm giao dịch trên blockchain.Trường txid sẽ không tồn tại nếu1) thanh toán được thực hiện thông qua p2p (Người trả tiền đã rút tiền từ tài khoản Cryptomus của mình đến địa chỉ được chỉ định trong hóa đơn và thanh toán được thực hiện mà không cần blockchain, chỉ trong hệ thống của chúng tôi)2) Chưa thanh toán3) Có gì đó không ổn với khoản thanh toán hoặc khách hàng đã mắc lỗi và chúng tôi đã đánh dấu là "đã thanh toán" theo cách thủ công |
| sign | Chữ ký |
Sự định nghĩa
Loại hóa đơn (ví / thanh toán)Sự định nghĩa
uuid của thanh toánSự định nghĩa
ID đơn hàng trong hệ thống của bạn (để xác định đơn hàng)Sự định nghĩa
Số tiền của hóa đơnSự định nghĩa
Số tiền thực tế khách hàng đã trảSự định nghĩa
Số tiền thực tế khách hàng đã thanh toán bằng USDSự định nghĩa
Số tiền được thêm vào số dư của người bán, sau khi đã trừ đi tất cả hoa hồng.Sự định nghĩa
Số tiền hoa hồng của CryptomusSự định nghĩa
Hóa đơn đã được hoàn tất hay chưa. Khi hóa đơn đã được hoàn tất, không thể thanh toán hóa đơn (hóa đơn đã được thanh toán hoặc đã hết hạn).Sự định nghĩa
Trạng thái thanh toánCác tùy chọn có sẵn:- confirm_check- paid- paid_over- fail- wrong_amount- cancel- system_fail- refund_process- refund_fail- refund_paidSự định nghĩa
Địa chỉ ví của người trả tiềnSự định nghĩa
uuid của ví tĩnhSự định nghĩa
Mạng blockchain nơi thanh toán được thực hiệnSự định nghĩa
Tiền tệ hóa đơnSự định nghĩa
Tiền tệ mà khách hàng thực sự đã thanh toánSự định nghĩa
Chuỗi thông tin bổ sung mà bạn đã cung cấp khi tạo hóa đơnSự định nghĩa
Thông tin về loại tiền tệ mà khoản thanh toán sẽ được tự động chuyển đổi. Việc chuyển đổi được thực hiện từ payer_currency sang USDTTrường chuyển đổi sẽ không tồn tại nếu bạn chưa bật chức năng chuyển đổi tự động cho payer_currency (ví dụ: tự động chuyển đổi BTC sang USDT) Kết cấuSự định nghĩa
Băm giao dịch trên blockchain.Trường txid sẽ không tồn tại nếu1) thanh toán được thực hiện thông qua p2p (Người trả tiền đã rút tiền từ tài khoản Cryptomus của mình đến địa chỉ được chỉ định trong hóa đơn và thanh toán được thực hiện mà không cần blockchain, chỉ trong hệ thống của chúng tôi)2) Chưa thanh toán3) Có gì đó không ổn với khoản thanh toán hoặc khách hàng đã mắc lỗi và chúng tôi đã đánh dấu là "đã thanh toán" theo cách thủ côngSự định nghĩa
Chữ ký
Cấu trúc của convert
| Tên | Sự định nghĩa |
|---|---|
| to_currency | Mã tiền tệ mà khoản thanh toán sẽ được chuyển đổi |
| commission | Phí chuyển đổi |
| rate | Tỷ lệ chuyển đổi |
| amount | Số tiền chuyển đổi theo đơn vị tiền tệ được thêm vào số dư của người bán, sau khi đã trừ đi tất cả hoa hồng.số tiền ở đây bằng merchant_amount * rate |
Sự định nghĩa
Mã tiền tệ mà khoản thanh toán sẽ được chuyển đổiSự định nghĩa
Phí chuyển đổiSự định nghĩa
Tỷ lệ chuyển đổiSự định nghĩa
Số tiền chuyển đổi theo đơn vị tiền tệ được thêm vào số dư của người bán, sau khi đã trừ đi tất cả hoa hồng.số tiền ở đây bằng merchant_amount * rate
Ví dụ phản hồi
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}Xác minh webhook
Vì khi nhận webhooks, bạn sẽ phát hành sản phẩm hoặc ghi có vào số dư của người dùng, nên bạn cần đảm bảo rằng mình đang nhận webhooks từ Cryptomus chứ không phải từ bất kỳ ai khác.
Chúng tôi khuyên bạn nên kiểm tra theo cả hai cách:
- Sử dụng danh sách trắng địa chỉ IP và chỉ cho phép các yêu cầu gọi lại url_callback từ các IP của chúng tôi. Chúng tôi gửi webhooks từ IP. 91.227.144.54
- Xác minh chữ ký trong mọi webhook gửi đến url_callback của bạn, hãy đọc thêm về điều này bên dưới.
Xác minh chữ ký webhook
Khóa API i của bạn là bí mật và không ai ngoài bạn và Cryptomus được biết. Vì vậy, khi xác minh chữ ký, bạn sẽ chắc chắn rằng webhook được gửi bởi Cryptomus.
Chúng tôi tạo ra một dấu hiệu bằng thuật toán này. Băm MD5 của nội dung yêu cầu POST được mã hóa theo base64 và kết hợp với khóa API của bạn.
Vì chữ ký nằm trong phần thân của yêu cầu, để xác minh nó, bạn cần trích xuất chữ ký từ phần thân phản hồi, tạo một hàm băm từ phần thân và API KEY của bạn và khớp nó với tham số dấu hiệu.
Một ví dụ trong php:
Để nhận dữ liệu json được gửi qua đường bưu điện đến trình xử lý webhook của bạn:
1$data = file_get_contents('php://input');
2$data = json_decode($data, true);Giả sử chúng ta nhận được webhook với dữ liệu trong cái này mảng
Đầu tiên, chúng ta cần trích xuất dấu hiệu từ mảng:
1$sign = $data['sign'];
2unset($data['sign']);Bây giờ chúng ta hãy tạo một dấu hiệu bằng cách sử dụng khóa thanh toán api của chúng ta:
1$hash = md5(base64_encode(json_encode($data, JSON_UNESCAPED_UNICODE)) . $apiPaymentKey);Cuối cùng, chúng ta có thể kiểm tra xem dấu hiệu chúng ta tạo ra bằng khóa thanh toán API có giống với dấu hiệu xuất hiện trên webhook hay không.
1if (!hash_equals($hash, $sign)) {
2 return new InvalidHashException();
3}
4
5// or
6
7if ($hash !== $sign) {
8 return new InvalidHashException();
9}Tại thời điểm này, bạn có thể chắc chắn rằng webhook đến từ Сcryptomus và bạn đã nhận được tất cả dữ liệu một cách chính xác
Có sự khác biệt khi mã hóa một mảng dữ liệu trong PHP và các ngôn ngữ khác. PHP có thể thoát dấu gạch chéo, trong khi một số ngôn ngữ khác thì không. Do đó, bạn có thể gặp phải lỗi không khớp dấu. Bạn phải thoát dấu gạch chéo bằng dấu gạch chéo ngược để mã hóa hoạt động bình thường.
trong 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"}trong 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