Webhook

Webhook是一種支付資訊的回饋方式。
當發票狀態變更時，會向建立發票時指定的 url_callback 發送 POST 請求。

回覆

響應參數

姓名定義
type發票類型（錢包/付款）
uuid付款的 uuid
order_id您系統中的訂單 ID（用於識別訂單）
amount發票金額
payment_amount客戶實際支付金額
payment_amount_usd客戶實際支付的美元金額
merchant_amount加到商家餘額中的金額，扣除所有佣金。
commissionCryptomus 佣金金額
is_final發票是否已最終確定。如果發票已最終確定，則無法支付（發票已付款或已過期）
status付款狀態可用選項：• confirm_check• paid• paid_over• fail• wrong_amount• cancel• system_fail• refund_process• refund_fail• refund_paid
from付款人的錢包地址
wallet_address_uuid靜態錢包的uuid
network進行支付的區塊鏈網絡
currency發票幣種
payer_currency客戶實際支付的貨幣
additional_data建立發票時提供的附加資訊字串
convert有關付款將自動兌換成的貨幣的資訊。兌換將從 payer_currency 轉換為 USDT如果您沒有啟用 payer_currency 的自動轉換功能（例如自動將 BTC 轉換為 USDT），則 convert 欄位將不存在。 結構
txid區塊鏈上的交易哈希。如果出現以下情況，txid 欄位將不存在1）付款是透過 p2p 支付的（付款人從他的 Cryptomus 帳戶中提取資金到發票中指定的地址，並且付款是在沒有區塊鏈的情況下進行的，僅在我們的系統中進行）2) 未付款3）付款出現問題或客戶犯了錯誤，我們手動將其標記為“已付款”
sign簽名

定義

發票類型（錢包/付款）

定義

付款的 uuid

定義

您系統中的訂單 ID（用於識別訂單）

定義

發票金額

定義

客戶實際支付金額

定義

客戶實際支付的美元金額

定義

加到商家餘額中的金額，扣除所有佣金。

定義

Cryptomus 佣金金額

定義

發票是否已最終確定。如果發票已最終確定，則無法支付（發票已付款或已過期）

定義

付款狀態可用選項：- confirm_check- paid- paid_over- fail- wrong_amount- cancel- system_fail- refund_process- refund_fail- refund_paid

定義

付款人的錢包地址

定義

靜態錢包的uuid

定義

進行支付的區塊鏈網絡

定義

發票幣種

定義

客戶實際支付的貨幣

定義

建立發票時提供的附加資訊字串

定義

有關付款將自動兌換成的貨幣的資訊。兌換將從 payer_currency 轉換為 USDT如果您沒有啟用 payer_currency 的自動轉換功能（例如自動將 BTC 轉換為 USDT），則 convert 欄位將不存在。 結構

定義

區塊鏈上的交易哈希。如果出現以下情況，txid 欄位將不存在1）付款是透過 p2p 支付的（付款人從他的 Cryptomus 帳戶中提取資金到發票中指定的地址，並且付款是在沒有區塊鏈的情況下進行的，僅在我們的系統中進行）2) 未付款3）付款出現問題或客戶犯了錯誤，我們手動將其標記為“已付款”

定義

簽名

結構 convert

姓名定義
to_currency付款將轉換至的貨幣代碼
commission轉換費
rate轉換率
amount以 to_currency 為單位的轉換金額已加到商家餘額中，並扣除所有佣金。此處的金額等於商家金額 * 費率

定義

付款將轉換至的貨幣代碼

定義

轉換費

定義

轉換率

定義

以 to_currency 為單位的轉換金額已加到商家餘額中，並扣除所有佣金。此處的金額等於商家金額 * 費率

回應範例


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}
複製

Webhook 驗證

由於透過接收 webhook，您可以發布產品或記入用戶餘額，因此您需要確保您接收的是來自 Cryptomus 而不是其他任何人的 webhook。

我們建議您從兩個方面進行檢查：

  • 使用 IP 位址白名單，僅允許來自我們 IP 位址的 url_callback 請求。我們從 IP 位址 91.227.144.54 發送 Webhook。
  • 驗證進入 url_callback 的每個 webhook 中的簽名，請閱讀下文以了解更多資訊。

驗證 webhook 簽名

您的 API 金鑰是保密的，除了您和 Cryptomus 之外，任何人都無法知道。因此，在驗證簽章時，您可以確定該 Webhook 是由 Cryptomus 發送的。

我們使用此演算法創建一個標誌。 POST 請求正文的 MD5 雜湊以 base64 編碼並與您的 API 金鑰結合。

由於簽名來自請求主體，為了驗證它，您需要從回應主體中提取簽名，從主體和 API KEY 產生雜湊並將其與簽名參數進行匹配。

PHP 中的一個例子：

若要接收透過郵寄方式傳送到您的 webhook 處理程序的 json 資料：


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

假設我們收到了包含資料的 webhook 這 大批
首先，我們需要從數組中提取符號：


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

現在讓我們使用我們的 api 支付密鑰產生一個標誌：


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

最後，我們可以檢查使用我們的 API 支付金鑰產生的簽章是否等於傳送到 webhook 的簽章。


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

此時，您可以確定該 webhook 來自 Сryptomus，並且您已正確收到所有數據

在 PHP 和其他語言中，對數組資料進行編碼時存在差異。 PHP 會轉義斜杠，而有些其他語言則不會。因此，您可能會遇到符號不符的情況。您必須使用反斜線轉義斜線才能使其正常運作。

在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"}
複製

在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
複製