错误码说明

商户 API 统一返回 JSON：{ "code": 0, "msg": "ok", "data": ... }。

• code = 0：成功
• code ≠ 0：失败，msg 为错误描述（用于日志与提示）

HTTP 状态码在多数业务错误场景仍为 200；请以 code 判断成功与否。

中国常见场景

msg	说明	处理建议
countryCode and currency must match merchant country config	须使用 CN / CNY	与开户配置一致
merchant balance insufficient	CNY 余额不足无法代付	充值或调账后再试
收款信息校验失败	银行/户名/卡号不符合规则	核对联行号与开户名

商户鉴权与安全

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	缺少商户订单号
countryCode and currency are required	缺少国家/币种
countryCode and currency must match merchant country config	与开户国家不一致

回调相关

场景	说明
未返回 OK	平台将重试回调（退避：30s → 5m → 30m，最多约 200 次）
验签失败	不要更新订单为成功，记录日志并告警

重试建议

场景	建议
签名/时间戳/nonce 错误	修正后重试，勿盲目重放
余额不足	充值后使用 新 merchantOrderNo 或原单查询状态
网络超时	先 查询订单 再决定是否重试创建