3- 3、回調

當訂單處理完成後，系統會向商家配置的回呼位址發送通知訊息。

回呼位址配置

下單時可透過 notifyUrl 參數指定本次訂單專屬回呼位址，該位址將覆寫商家後台設定的預設回呼位址。

param.put("notifyUrl", "http://{域名}/callback/notifyUrl");

若下單時未傳入 notifyUrl，系統將回呼商家後台設定的預設回呼位址。預設回呼位址由商家建立時提供，並可在營運管理後台進行維護。

回呼請求方式

HTTP Method

POST

Content-Type

application/json

回呼資料範例

{
  "amount": "100",
  "bizType": "WITHDRAW_ANY_DIGITAL_WALLET",
  "blockchain": {
    "network": "TRON",
    "receiverAddress": "THcJ2FeNBkuzd4PZBpRans6tx9QGg9KHRt",
    "senderAddress": "TE35TrUfHjbGEBsVS6zVXdHS8HxXCWwC2y",
    "txIndex": "2",
    "txId": "d848e4b62ec6925b8b3ff49dbc4d839f3f88508497c3af525f0c8293cb303ab3"
  },
  "currency": "CNY",
  "localOrderId": "TestOTM0625ROB016",
  "merchantActualAmount": "138.12",
  "merchantCurrency": "CNY",
  "merchantId": 302992856974,
  "merchantPaidAmount": "100",
  "notifyTime": 1772173006425,
  "orderCreateTime": 1772172958082,
  "orderId": "472515854147845",
  "status": "SUCCESS",
  "type": "WITHDRAW",
  "userAmount": "14.971722",
  "userCurrency": "USDT",
  "userMinerFee": "0",
  "isReissue": false,
  "userReceivableAmount": "14.971722",
  "rate": "6.71080951",
  "rateExpression": "1USDT≈6.7108CNY",
  "sign": "2c27c7e8184cc709a64ad502ee42eab7",
  "key": "9yUreYgTRtit39Dy"
}

**為滿足業務發展需要，回呼參數未來可能新增欄位。新增欄位預設參與簽章計算（除簽章規則中特別說明的欄位外），因此商家系統應具備向前相容能力，避免因欄位擴充導致驗簽失敗。 **

回呼參數說明

參數名稱	類型	參與簽名	參數意義	參數說明
`amount`	`decimal`	是	訂單金額
`bizType`	`enum`	是	訂單類型	訂單類型說明如下
`blockchain`	`object`	是	鏈交易信息	鏈上交易信息，僅當 `isBlockchain=true` 時返回
└network	`String`	是	主網
└receiverAddress	`String`	是	接收位址
└senderAddress	`decimal`	是	傳送位址
└txId	`String`	是	交易ID	區塊鏈交易哈希
└txIndex	`String`	是	交易索引	交易索引（批次轉帳場景）
`currency`	`String`	是	幣種	訂單幣種
`key`	`String`	是	商家 key
`localOrderId`	`String`	是	商家訂單號碼
`merchantActualAmount`	`decimal`	是	商家實際收付金額
`merchantCurrency`	`String`	是	商家結算幣種
`merchantId`	`String`	是	商家號碼
`merchantPaidAmount`	`decimal`	是	商家應收或應付金額
`merchantUserId`	`String`	是	商家用戶 ID
`notifyTime`	`long`	是	回呼時間	回呼通知時間
`orderCreateTime`	`long`	是	訂單建立時間
`orderId`	`String`	是	訂單號碼	平台訂單號碼（唯一）
`status`	`String`	是	支付狀態	SUCCESS 、 FAIL（說明如下）
`type`	`String`	是	訂單類型	PAYMENT 、WITHDRAW（說明如下）
`userAmount`	`decimal`	是	用戶實收或實付金額
`userCurrency`	`String`	是	用戶幣種
`userMinerFee`	`String`	是	礦工費
`userReceivableAmount`	`String`	是	用戶應付或應收金額
`isReissue`	`Boolean`	是	是否補發	是否補發回呼
`rate`	`string`	是	匯率
`rateExpression`	`string`	是	匯率表達式
`sign`	`String`	否	簽章值	md5 簽章（詳見簽章演算法）

status 狀態說明

狀態值	說明
`SUCCESS`	已完成
`FAIL`	已失敗

type 類型說明

類型值	說明
`PAYMENT`	付款
`WITHDRAW`	提款

bizType 業務類型說明

bizType	說明
`PAYMENT_WALLET_SCAN`	VPAY 皮夾掃碼付款
`PAYMENT_TRANSFER`	數位貨幣綁定位址直充
`PAYMENT_ANY_DIGITAL_SCAN`	數位貨幣任一金額掃碼付款
`PAYMENT_FIXED_DIGITAL_SCAN`	數位貨幣固定金額掃碼支付
`WITHDRAW_WALLET`	提現至 VPAY 皮夾
`WITHDRAW_ANY_DIGITAL_WALLET`	提現至任意數位錢包
`BATCH_PAY`	大量代付

回呼回應要求

商家成功處理回呼後，必須回傳以下內容：

success

系統收到字串 success 後，視為回呼處理成功，不再重複發送。

回呼重試機制

若出現以下情況：

未收到回應
回傳內容不是 success
HTTP 請求異常
服務超時

系統將自動重試發送回呼通知。

最大重試次數

14次

重試間隔

建議商家系統依照 orderId 實現冪等處理，避免因重複回呼導致業務資料重複處理。

簽名校驗

收到回調通知後，商家必須先進行簽章驗證，驗證通過後再執行業務邏輯。簽章演算法與下單請求簽章規則完全一致，請參考《2. 如何簽章》。

驗簽流程

取得回呼參數中的 sign
從參數中移除 sign
將商家 key 放入參數
使用商家 secret 依簽章規則重新計算簽名
比較計算結果與回呼中的 sign 是否一致

只有驗簽成功後，才應處理訂單業務。

Java 驗簽範例

public void notify(JSONObject data) {

    log.info("收到回调通知：{}", data.toJSONString());

    String key = "your_key";
    String secret = "your_secret";
   
    String sign = data.getString("sign");

    data.put("key", key);
    data.remove("sign");
   
    String calculatedSign = SignUtils.getSign(data, secret);

    if (!calculatedSign.equals(sign)) {
        throw new DxBizException("签名验证失败");
    }
    // 业务处理逻辑
}

回呼位址配置​

回呼請求方式​

回呼資料範例​

回呼參數說明​

status 狀態說明​

type 類型說明​

bizType 業務類型說明​

回呼回應要求​

回呼重試機制​

最大重試次數​

重試間隔​