代付回调

代付回调采用和收款回调相同的签名头和重试机制。

平台仅在代付进入 status=confirmed 或 status=failed 终态时回调。

POST创建代付订单时请求体中的 notifyUrl

请求头

字段名称	字段类型	是否必填	说明
content-type	application/json	是	固定为 application/json。
x-callback-timestamp	string	是	回调发送时的毫秒时间戳。
x-callback-nonce	string	是	回调随机串。
x-callback-signature	string	是	HMAC-SHA256(apiKey, timestamp + "." + nonce + "." + rawBody)。
x-callback-signature-algorithm	string	是	固定为 HMAC-SHA256。
x-callback-signature-version	string	是	固定为 v1。

接口参数

字段名称	字段类型	是否必填	说明
merchantUid	string	是	Merchant UID。
orderNo	string	是	平台代付订单号。
merchantOrderNo	string \| null	是	商户订单号。
chainCode	string	是	链编码。
tokenSymbol	string	是	代币符号。
fromAddress	string \| null	是	付款地址。
toAddress	string	是	收款地址。
txHash	string \| null	否	链上哈希。
amount	string	是	代付金额。
status	string	是	代付终态：confirmed 或 failed。
failedStage	string	否	仅 status=failed 时返回。

请求示例

{
  "merchantUid": "880001",
  "orderNo": "PO1776193200A1B2C3D4",
  "merchantOrderNo": "PO202604150001",
  "chainCode": "TRON",
  "tokenSymbol": "USDT",
  "fromAddress": "TNjBrNq2a9FK2vwu4W9C1QdLKSZ42Yx5YY",
  "toAddress": "TS7b7iD8G2PaPqK1TqSmLJ9nrrYH4oKX1S",
  "txHash": "b3d4fb0cb11eb86bb906d1e0ee3b84e17f40d5441d1e4c651ea46920a48a9a01",
  "amount": "35.500000",
  "status": "confirmed"
}

接口返回

字段名称	字段类型	是否必填	说明
HTTP Status	200-299	是	任意 2xx 都视为成功。
Response Body	string \| json	否	内容可自定义。

返回示例

HTTP/1.1 200 OK
Content-Type: text/plain

success

代码示例

Express 处理示例

app.post('/merchant/callback', (req, res) => {
  if (req.body.status === 'confirmed') {
    // 代付成功
  }

  if (req.body.status === 'failed') {
    // 代付失败
  }

  return res.status(200).send('success');
});

说明

请按 orderNo 做幂等处理；系统只自动推送 confirmed 或 failed 终态。