收款回调

收款订单成功完成后才会回调商户服务器，回调体固定为 status=completed。

系统仅推送收款、付款的最终结果，以 HTTP 2xx 作为成功标准并立即停止；首次失败后 1 分钟进行第 2 次投递，再失败则 5 分钟后进行第 3 次投递，总计最多 3 次。回调业务时间统一为北京时间 YYYY/MM/DD HH:mm:ss。

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	是	商户订单号。
bindKey	string \| null	是	会员充值场景下的绑定键；共享收款订单通常为空。
expectedAmount	string	是	订单金额。
paidAmount	string	是	实际支付金额。
chainCode	string	是	链编码。
tokenSymbol	string	是	代币符号。
txHash	string	是	链上交易哈希。
fromAddress	string \| null	是	付款地址。
status	string	是	收款成功终态，固定为 completed。

请求示例

{
  "merchantUid": "880001",
  "orderNo": "PI1776193200123ABCD1234",
  "merchantOrderNo": "M202604150001",
  "bindKey": "USER_90001",
  "expectedAmount": "100.000000",
  "paidAmount": "100.000000",
  "chainCode": "TRON",
  "tokenSymbol": "USDT",
  "txHash": "f7f17891f52c35d0c93170f0d12bb347ac16ab34853b4bc8dcf7fd0a8c9aa321",
  "fromAddress": "TS7b7iD8G2PaPqK1TqSmLJ9nrrYH4oKX1S",
  "status": "completed"
}

接口返回

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

返回示例

HTTP/1.1 200 OK
Content-Type: application/json

{
  "ok": true
}

代码示例

Node.js 回调验签示例

import express from 'express';
import { verifyCallbackSignature } from 'uugate-openapi-sdk';

const app = express();
app.use(express.json({
  verify: (req, _res, buffer) => {
    req.rawBody = buffer.toString('utf8');
  },
}));

app.post('/merchant/callback', (req, res) => {
  const valid = verifyCallbackSignature({
    apiKey: process.env.UUGATE_API_KEY,
    timestamp: req.header('x-callback-timestamp'),
    nonce: req.header('x-callback-nonce'),
    signature: req.header('x-callback-signature'),
    rawBody: req.rawBody || '',
  });

  if (!valid) {
    return res.status(401).json({ ok: false });
  }

  return res.status(200).json({ ok: true });
});

说明

回调验签使用 apiKey，而不是开放接口请求头里的 x-signature。
验签后核对商户、订单、币种、网络和金额，在事务中按平台订单号幂等记录付款与业务结果，成功持久化后才返回 2xx；重复通知不得重复发货或入账。
会员充值场景建议直接使用 bindKey 作为会员标识，不需要再额外维护 orderNo 到会员 ID 的映射表。