错误码说明

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

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

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

巴基斯坦常见场景

msg	说明	处理建议
countryCode and currency must match merchant country config	创建时误传了非 PK 国家/币种	创建订单勿传 countryCode、currency；由商户号自动识别
unsupported bankCode	bankCode 不在支持列表	使用 附录 bankCode 枚举 中的大写编码
pay_type must be BANK_TRANSFER or EWALLET	pay_type 值无效	银行转账传 BANK_TRANSFER，电子钱包传 EWALLET
bankCode is required when pay_type is EWALLET	电子钱包代付未传 bankCode	传入对应钱包的支付工具编码
EWALLET payment tool not found or payout is disabled for bankCode	没有匹配且启用代付的电子钱包工具	检查 bankCode，或联系运营启用对应 EWALLET 工具的“支持付”
channel is under maintenance	当前 bankCode 或支付渠道维护中	稍后重试，或联系运营确认可用渠道
merchant balance insufficient	PKR 钱包余额不足	充值或调账后再试

商户鉴权与安全

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 is required	代付缺少 bankCode
pay_type must be BANK_TRANSFER or EWALLET	代付方式只接受 BANK_TRANSFER 或 EWALLET
payee_realname is required / payee_account is required	缺少收款人必填字段
countryCode and currency must match merchant country config	创建时误传了与开户国家不一致的参数（应省略这两项）

回调相关

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

重试建议

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