# 回調交易結果

# 回調接口驗簽

驗簽目的

API 請求在通過公網傳輸過程中，有被中間人篡改的風險。為確保回調數據的完整性與可信性，平台支持並強烈建議商戶在接收回調時進行簽名驗簽。

設置方式

登入【收銀台後台】→【開發者中心】→【回調地址】→ 新增/編輯。

驗簽步驟

驗簽邏輯與接口請求簽名大體一致，區別在於數據來源為接收到的回調內容。

  1. 獲取簽名

從 HTTP 請求 Header 中讀取簽名字段：

sign: {平台生成的签名字符串}
  1. 獲取回調參數體

將回調 Body 中的 JSON 參數以 key-value 形式存入一個 Map（字典）結構中。

  1. 添加公共參數

從 Header 中再取出以下字段，並一併加入 Map 中參與驗簽：

  • access_key
  • timestamp
  • nonce
  1. 構造待簽名字符串

將 Map 中的所有 key 按照 ASCII 字典序從小到大排序，並拼接為如下格式的字符串：

key1=value1&key2=value2&...&keyN=valueN
  1. 執行簽名計算

使用商戶後台綁定的 secret_key 對上述字符串進行以下處理：

  • 使用 HMAC_SHA1 算法加密
  • 將結果進行 Base64 編碼，得到本地 sign 值
  1. 比對簽名

將本地生成的 sign 與 Header 中平台傳來的 sign 進行比對：

  • ✅ 一致 → 驗簽通過，可處理業務邏輯
  • ❌ 不一致 → 拒絕處理，建議記錄日誌以供排查

# 收款回調

回調數據範例

{
  "currencyType": "USD",
  "orderActualAmount": "1",
  "orderId": "OCRYPPAID202307310902391690794159441DOCKER020000000400001108",
  "tradeHash": "0x806d5b3da29c8426a644e2ded85b865b37504dcdec4cfb9db13af5e962815528",
  "orderFee": "1",
  "orderStatus": "Completed",
  "chainType": "ETH",
  "externalOrderId": "402297358314559082",
  "addressTo": "0xe072c63c1e04f8c6f36133f6629f66778147d5d8",
  "orderAmount": "1",
  "orderTime": 1690794159000,
  "exchangeRate": "0.983",
  "orderStatusCode": 4,
  "orderPayTime": 1690794247000,
  "addressFrom": "0x0cbfd17ae9e1d6d881b2cade71277f48abf64d24",
  "tokenType": "USDT"
}

回調字段說明

參數名 類型 描述
currencyType String 法幣類型（如 USD）
orderActualAmount String 實際支付金額
orderId String 平台訂單ID
tradeHash String 區塊鏈交易哈希
orderFee String 手續費金額
orderStatus String 訂單狀態文本（如 Completed）
orderStatusCode int64 訂單狀態碼（見下方說明）
chainType String 區塊鏈主鏈類型（如 ETH）
externalOrderId String 商戶訂單號
addressTo String 收款地址
addressFrom String 出款地址
orderAmount String 原始訂單金額
orderTime int64 訂單創建時間（Unix 毫秒）
orderPayTime int64 實際支付時間（Unix 毫秒）
exchangeRate String 匯率
tokenType String 加密代幣類型（如 USDT）
markStatus String 標記狀態（如需支援）
errorMsg String 錯誤信息（中文）
errorMsgEn String 錯誤信息（英文）

訂單狀態碼說明（orderStatusCode）

狀態碼 描述
1 待支付：訂單創建成功，等待用戶付款
2 鏈上確認中：用戶點擊「我已付款」，等待鏈上確認
4 已完成：支付成功，平台會自動發送回調通知
8 支付金額不匹配：仍回調通知，請根據實際金額入賬
16 超時收款：用戶未按時支付，不再回調通知
32 未支付：地址過期回收，不再處理

⚠️ 回調處理建議

  • 回調一旦驗簽通過且 orderStatusCode == 4，即可視為支付成功，應立即執行上分 / 業務處理。
  • 平台可能因網絡等原因重複推送回調，請務必做好冪等處理，避免重複入賬。
  • 若驗簽失敗或數據異常，請記錄日誌並返回錯誤響應，平台將在最多 30 分鐘內自動重試 2 次。

手動回調說明

商戶可在後台訂單管理中手動觸發回調，用於修復漏回調情況。但請注意：

  • 若訂單狀態非終態（如：待支付、確認中），不建議手動回調。
  • 若手動回調時訂單尚未完成，平台在狀態變為終態後仍會再次回調，請商戶做好業務層面的去重處理。

# 代付回調

回調數據範例

{
  "orderAmount": "1",
  "orderTime": 1690794160000,
  "orderId": "OCRYPDRAW202307310902401690794160841DOCKER020000000200001109",
  "orderStatusCode": 2,
  "tradeHash": "0xe9d043c9cbdb96ed7a71c5a0923baabe9e23316b3f1b0a01975bcd6d69b41fa3",
  "orderFee": "0.01",
  "orderStatus": "Completed",
  "orderPayTime": 1690794182000,
  "chainType": "ETH",
  "externalOrderId": "622257420681202921",
  "tokenType": "USDT",
  "addressTo": "0xa8666442fA7583F783a169CC9F5449ec660295E8"
}

回調字段說明

參數名 類型 描述
orderAmount String 訂單金額
orderTime int64 訂單創建時間（Unix 毫秒）
orderId String 平台訂單ID
orderStatusCode int64 訂單狀態碼（見下方說明）
tradeHash String 區塊鏈交易哈希
orderFee String 手續費金額
orderStatus String 訂單狀態描述（如 Completed）
orderPayTime int64 出款完成時間（Unix 毫秒）
chainType String 區塊鏈主鏈類型（如 ETH）
externalOrderId String 商戶訂單號
tokenType String 加密代幣類型（如 USDT）
addressTo String 收款地址

訂單狀態碼說明（orderStatusCode）

狀態碼 描述
1 已受理
2 已完成（出款成功）
4 出款失敗
8 待審批
16 拒絕出款

⚠️ 回調處理建議

  • 當 orderStatusCode == 2 且驗簽通過，即可確認出款成功，請執行上分 / 發貨 / 狀態更新等操作。
  • 回調推送支援多次重發，請務必支援冪等性處理。
  • 若返回非 200 響應或驗簽失敗，平台將嘗試再次回調。

手動回調說明

商戶可登入後台進行手動觸發回調操作。請注意以下事項：

  • 不建議對「非終態訂單」發起手動回調，如：狀態為「已受理」、「待審批」等；
  • 若手動回調的訂單仍處於非終態，未來狀態變更為終態時平台仍將再次回調，商戶需做好業務層面的冗餘處理；

# 回調響應

說明

  • 所有回調均包含簽名字段，建議商戶務必對回調進行驗簽，確保回調內容未被篡改。
  • 商戶在收到回調數據並處理完成後，需以 JSON格式 響應網關如下數據：

範例響應（成功）

{
  "code": 200,
  "success": true
}

回調補發機制說明（重要）🔥

為確保回調通知的穩定送達與業務一致性，平台設計了多次重試策略。當商戶系統未能成功響應回調時（如網絡超時、返回非200狀態碼等），系統將按以下規則進行回調補發：

回調重試節奏（共 4 次）：

嘗試次數 間隔時間（約） 說明
第 1 次 約 2 分鐘後 首次失敗後觸發第一次重試
第 2 次 約 2 分鐘後 第一次重試失敗後觸發第二次重試
第 3 次 再約 11分鐘後 第二次重試失敗後再次重試
第 4 次 再約 2分鐘後 第三次重試失敗後進入下一次重試

注意：以上間隔時間為系統內部調度間隔，商戶後台所記錄的「回調時間」包含了商戶處理/響應時間，因此顯示上可能與實際推送時間存在 1 分鐘左右誤差。

實際情況提醒

  • 當線上訂單量較大時，回調可能存在隊列延遲，請確保服務端支援高併發處理能力；
  • 每次回調均為冪等操作，建議商戶側務必支援冪等判斷；
  • 最多 4 次重試推送仍失敗後，則不再自動重試，建議通過後台手動觸發回調。

回調響應參數

Param Type Required Description
code int ✅ 狀態碼，成功為 200
success boolean ✅ 響應是否成功

回調響應要求

商戶服務需返回如下標準響應：

{
  "code": 200,
  "success": true
}

響應類型

HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8

⚠️ 特別說明

  • 平台只判斷 HTTP Status Code 是否為 200，只要狀態碼為 200，即視為回調成功，不再校驗響應內容。
  • 若返回非 200 狀態（如 500 / 404），則會視為失敗並觸發重試機制。

商戶建議實踐

  • 驗簽成功且業務處理完成後立即返回 200。
  • 若處理失敗，記錄日誌並確保平台後續補發能正常接收。
  • 建議使用異步任務處理回調內容，避免阻塞響應。

# 回調通知 URL 配置

支援兩種通知地址配置方式：

  1. 【商戶後台】配置統一回調地址
  • 可於「商戶後台」→「開發者中心」中進行配置。
  • 適用於大部分訂單共用回調處理邏輯的場景。

img

  1. 訂單級別手動指定回調地址 (notifyUrl)
  • 在建立訂單的介面中可傳入 notifyUrl 欄位。
  • 若訂單中指定了 notifyUrl 參數，則系統將僅使用該地址作為回調通知的目標地址。

地址優先級說明

訂單中的 notifyUrl 優先級高於統一配置的回調地址。

響應狀態碼優先級說明

平台以 HTTP 響應狀態碼 (status_code) 是否為 200 作為通知是否成功的唯一判斷標準。

具體規則如下：

  • ✅ 只要商户系統返回 HTTP 200 ，平台即認為回調成功
    • 此時即使回傳的內容不是 { "code": 200, "success": true } 也會被忽略。
  • ❌ 如果回傳的 status_code ≠ 200（例如 400/500）或無響應，則判定為失敗，平台將自動進行重試推送。

← 1、建立收款 →