回调通知

代收 / 代付到达终态时，Smilepayz 向你的 URL 发 HTTP POST。

仅 API 订单

只有通过 代收 / 代付 API 创建的订单会回调；商户后台 支付链接 订单不会。

流程：配 URL → 验签并更新订单 → 返回 SUCCESS。

1. 配置回调 URL

1. 登录 商户后台，顶部切到 Sandbox（或生产）。
2. Configuration → API Setting → API Notify Address：
   • Payin — 代收通知
   • Withdraw — 代付通知
3. 点 Save。

建议 HTTPS（443）。生产 URL / IP 白名单见 集成信息。失败会重推，须幂等处理（勿重复入账）。

幂等键优先使用 `tradeNo`

重推时同一笔交易的 tradeNo 不变。墨西哥等地区的代收子订单可能与主单共享同一个 orderNo，但各自有独立 tradeNo——交易级幂等请以 tradeNo 为准，不要只按 orderNo 去重。详见 墨西哥代收 · 子订单交易与回调逻辑。

2. 验签（与下单签名不同）

处理订单前先验签。 规则、公钥、各语言代码见独立页（与发请求那套公式不同）：

相关回调验签→

3. Body 与响应

Body 为 JSON，常用字段：orderNo、tradeNo、merchantId、status、money、transactionTime（yyyy-MM-ddTHH:mm:ss，订单地区时区）。完整字段见各地区 代收 / 代付 → Notification/Callback。

验签并落库后，HTTP 200 响应体须为纯文本：

SUCCESS

注意

trim 后须精确等于 SUCCESS。不要返回 JSON / HTML，否则会重推。

沙盒怎么测

1. API 建一笔代收（paymentMethod 不能为空，如印尼 QRIS）。
2. 后台 Pay-in Order → Operate → Set Callback（成功 / 失败）。
3. 看 Callback Status。

生产环境终态会自动回调，无需点 Set Callback。

排查

问题	处理
收不到	URL 是否已 Save；防火墙 / HTTPS 证书
验签失败	见 回调验签
Set Callback 无效	须 API 建单；paymentMethod 不能为空
一直重推	是否 trim 后精确返回 SUCCESS