回调通知
回调通知
当代收或提现订单达到终态时，Smilepayz 会向您的服务器发送 HTTP POST 通知。本指南说明回调地址配置、沙盒测试、签名校验及响应方式。
概述
回调通知可帮助您的系统：
- 异步接收代收、提现订单状态更新
- 无需轮询查询接口即可确认订单结果
- 在校验签名后更新内部订单状态
仅 API 订单
回调仅针对通过 代收 / 代付 API 创建的订单发送。在商户后台 支付链接 中创建的订单无法与您的系统集成关联。
前提条件
处理回调前，请确认：
- 已准备可公网访问的回调地址（
http://或https://，建议使用 443 端口的 HTTPS） - 已从沙盒或生产环境的集成信息获取 平台公钥（Platform Public Key）
- 服务端已实现签名校验，并能返回
SUCCESS
配置回调地址
沙盒环境
- 登录商户后台。
- 将顶部开关切换为 Sandbox（沙盒）。
- 进入 Configuration（配置） → API Setting（API 设置）。
- 在 API Notify Address（API 通知地址） 中填写：
- Payin — 代收完成后的通知地址
- Withdraw — 提现完成后的通知地址
- 点击 Save（保存）。
重试与幂等
后台可能对失败的回调自动重试。您的接口应每次校验签名，并对重复通知做幂等处理（同一 tradeNo / orderNo 不应重复入账）。
生产环境地址及 IP 白名单配置，见集成信息。
沙盒测试
沙盒中可在创建 API 订单后，从订单列表手动触发测试回调。
步骤 1：创建沙盒 API 订单
通过 API 创建代收订单（参见对应国家/地区的代收接口文档）。请求中 paymentMethod 不能为空（例如印尼可使用 QRIS）。
步骤 2：模拟回调
- 在商户后台（沙盒）打开 Pay-in Order（代收订单）。
- 搜索刚创建的订单。
- 在 Operate（操作） 列点击 Set Callback，模拟 成功 或 失败 通知。
- 在 Callback Status（回调状态） 列查看投递结果。
支付方式必填
沙盒创建订单时若 paymentMethod 为空，Set Callback 可能无法正常工作。请在 API 请求中传入有效的支付方式。
生产环境
真实支付或出款完成后，系统会自动发送回调，无需手动点击 Set Callback。
校验回调签名
每条回调都带有签名头。请使用 平台公钥 校验通过后再更新订单。
请求头
| 请求头 | 说明 |
|---|---|
Content-Type | application/json |
X-TIMESTAMP | 时间戳，如 2020-12-17T10:55:00+07:00 |
X-SIGNATURE | RSA 签名（Base64） |
待签名字符串
Smilepayz 使用平台私钥签名，您使用平台公钥验签：
stringToSign = tradeNo + "|" + X-TIMESTAMP
X-SIGNATURE = SHA256withRSA(smilepayz_private_key, stringToSign)
验签步骤
- 从请求头读取
X-SIGNATURE、X-TIMESTAMP。 - 从 JSON 请求体读取
tradeNo。 - 拼接
stringToSign = tradeNo + "|" + X-TIMESTAMP。 - 使用 平台公钥 以 SHA256withRSA 校验
X-SIGNATURE。 - 校验通过后处理状态更新；否则拒绝请求。
可使用 Tools / SDK 文档 中的 checkSha256RsaSignature，或参阅签名授权了解完整签名模型。
回调请求体（JSON）
回调 POST 请求体为 JSON，主要字段包括 orderNo、tradeNo、merchantId、status、money、transactionTime 等。
transactionTime 格式： yyyy-MM-ddTHH:mm:ss（与订单所属地区时区一致）。
完整字段说明见各国家/地区 代收 / 代付接口参考 → Notification/Callback → Body Parameters。
响应回调
校验并处理成功后，返回纯文本：
SUCCESS
请勿返回 JSON 或其他内容；否则系统可能视为投递失败并重试。
实现清单
- 配置地址 — 在沙盒/生产环境填写代收、提现通知地址。
- 获取平台公钥 — 见集成信息。
- 校验每条回调 — 未验签前不要信任请求体。
- 更新订单状态 — 根据
status映射内部流程。 - 返回
SUCCESS— 仅在业务侧安全落库后返回。
重要说明
- 务必验签 — 切勿信任未校验的回调。
- 使用正确公钥 — 沙盒与生产公钥不同。
- 幂等处理 — 重试可能导致同一通知多次到达。
- 仅 API 订单 — 商户后台支付链接订单不会触发集成回调。
故障排查
| 问题 | 处理建议 |
|---|---|
| 未收到回调 | 确认通知地址已保存；检查防火墙与 HTTPS 证书 |
| 验签失败 | 使用对应环境的平台公钥；确认 stringToSign 为 tradeNo|X-TIMESTAMP |
| 沙盒无 Set Callback | 须先通过 API 创建订单；paymentMethod 不能为空 |
| 回调反复重试 | 处理完成后以 HTTP 200 返回纯文本 SUCCESS |
支持
- 文档：各地区 API 参考与签名授权
- 技术支持：回调地址与签名相关问题
- 客服：账户与环境权限