回调接收与接口调试

图文步骤

按步骤在自己的后台操作，点击图片可放大查看。

1. 1

   进入开发者中心的“接收回调”，填写当前商户 UID 和 API Key。页面会显示该商户的调试 notifyUrl。点击“复制地址”，将这个地址用于需要观察回调的订单；也可以在下单工具中选择“使用调试地址”。

   

2. 2

   点击“开始接收回调”后，页面每 4 秒刷新，最多显示最近 20 条发往该调试地址的记录。“立即刷新”可主动查询；“停止接收”只停止当前页面轮询，不会撤销订单，也不会关闭服务端接收地址。未将 notifyUrl 指向该地址的订单不会出现在这里。

3. 3

   收款完成后才自动发送 completed 回调；代付在 confirmed 或 failed 时发送终态回调。仅创建订单、等待支付或正在确认时没有成功回调属正常情况。核对订单号、商户订单号、币种、金额、交易哈希、验签和投递状态；调试地址验签成功不代表你自己的业务系统已经处理成功。

4. 4

   准备自建服务时，参考页面下方完整回调服务代码，选择 Node.js 或 PHP。将服务部署到可公网访问的 HTTPS 地址，保留原始请求体 rawBody；用创建原订单时的 API Key 验证 HMAC-SHA256(timestamp + "." + nonce + "." + rawBody)，对照 x-callback-signature。不要把解析后重新格式化的 JSON 用来验签，也不要用请求头 x-signature 代替回调签名。

5. 5

   验签通过后，核对商户身份、订单关系、链和币种、金额以及业务终态；用数据库事务和唯一约束完成幂等更新，重复通知不能重复入账。业务处理成功或已可靠持久化到待处理队列后再返回 HTTP 2xx。无效签名拒绝处理；自己的服务发生异常时不要直接假报成功。

6. 6

   在本地用虚构测试密钥先验证：合法通知可通过；修改 body 后验签失败；同一通知重复发送只更新一次；处理中断可恢复。再将新订单 notifyUrl 改为自己的服务，核对该服务访问日志、应答和业务订单。非 2xx 或超时会触发最多 3 次投递：首次失败后 1 分钟再投递，再失败后 5 分钟投递第 3 次；不要假设平台会无限重试。