错误码说明
商户 API 统一返回 JSON：{ "code": 0, "msg": "ok", "data": ... }。
code = 0：成功code ≠ 0：失败，msg为错误描述（用于日志与提示）
HTTP 状态码在多数业务错误场景仍为
200；请以code判断成功与否。
商户鉴权与安全
| msg | 说明 | 处理建议 |
|---|---|---|
signature invalid | RSA2 验签失败 | 检查私钥、待签名字符串、Base64 |
merchant not found | 商户号不存在 | 核对 X-Merchant-No |
merchant inactive | 商户已停用 | 联系运营 |
merchant request expired | 时间戳超出 requestExpireSeconds | 同步服务器时钟 |
merchant duplicate nonce | Nonce 重复 | 每次请求生成新 nonce |
merchant ip not allowed | IP 不在白名单 | 提交出口 IP 给运营 |
订单与资金
| msg | 说明 | 处理建议 |
|---|---|---|
merchant order no already exists | 商户订单号重复 | 换新的 merchantOrderNo |
merchant order not found | 订单不存在 | 核对 orderNo / merchantOrderNo |
merchant balance insufficient | 代付时钱包余额不足 | 充值或调账后再试 |
amount must be greater than zero | 金额非法 | 检查 amount |
参数校验（示例）
| msg | 说明 |
|---|---|
merchantOrderNo is required | 缺少商户订单号 |
bankCode must be a platform bank code from upstream channel mappings for merchant country | bankCode 不在当前商户国家支持列表中 |
回调相关
| 场景 | 说明 |
|---|---|
未返回 OK | 平台将重试回调（退避：30s → 5m → 30m，最多约 200 次） |
| 验签失败 | 不要更新订单为成功，记录日志并告警 |
重试建议
| 场景 | 建议 |
|---|---|
| 签名/时间戳/nonce 错误 | 修正后重试，勿盲目重放 |
| 余额不足 | 充值后使用 新 merchantOrderNo 或原单查询状态 |
| 网络超时 | 先 查询订单 再决定是否重试创建 |