错误码
| code | message_key | 说明 |
|---|---|---|
10001 |
error.invalid_api_key |
API Key 无效或已停用 |
10002 |
error.invalid_signature |
签名错误 |
10003 |
error.timestamp_expired |
时间戳已过期 |
10004 |
error.nonce_repeated |
nonce 重复 |
10005 |
error.ip_not_allowed |
请求 IP 不在白名单 |
10006 |
error.permission_denied |
API Key 未开通该权限 |
10007 |
error.channel_api_key_mismatch |
通道与 API Key 不一致 |
10008 |
error.invalid_merchant_binding |
商户与 API Key 不匹配 |
10009 |
error.invalid_environment |
请求环境与凭证不匹配 |
10010 |
error.missing_parameter |
缺少必填参数 |
10011 |
error.invalid_parameter |
参数格式错误 |
10012 |
error.unsupported_currency |
不支持该币种 |
10013 |
error.unsupported_payment_method |
不支持该支付类型 |
10014 |
error.unsupported_bank |
银行或电子钱包不支持 / 无有效映射 |
10015 |
error.too_many_requests |
请求过于频繁或达到限额 |
10016 |
error.risk_rejected |
交易被风控拒绝 |
20001 |
error.merchant_not_tradeable |
商户当前不可交易 |
20002 |
error.merchant_not_found |
商户不存在 |
30001 |
error.channel_unavailable |
通道不可用 |
30002 |
error.channel_maintenance |
通道维护,暂停接收新单;已有正式订单继续处理 |
30007 |
error.provider_timeout |
支付服务响应超时 |
30008 |
error.provider_bad_response |
支付服务响应异常 |
40001 |
error.insufficient_balance |
可用余额不足 |
40002 |
error.amount_below_min |
金额低于最低限额 |
40003 |
error.amount_above_max |
金额高于最高限额 |
40004 |
error.invalid_amount |
金额格式或精度错误 |
50002 |
error.submission_conflict |
订单或会话创建冲突 |
50003 |
error.order_not_found |
订单或会话不存在 |
50006 |
error.cashier_unavailable |
收银台会话或当前配置不可用 |
50007 |
error.cashier_expired |
收银台会话已过期 |
50008 |
error.cashier_selection_conflict |
收银台通道或收款资料已锁定 |
50009 |
error.cashier_provider_message |
收银台提交失败;message 为安全过滤后的支付通道错误信息 |
90000 |
error.system_error |
系统错误 |
90001 |
error.provider_system_error |
支付服务暂时异常 |
自由匹配金额提示#
POST /api/v1/pay/create 与 POST /api/v1/payout/create 使用自由匹配 Key(merchant_global)且未指定 channel_code 时,创建被拒绝后会按当前商户、环境、币种和支付类型的有效绑定通道配置汇总金额边界:最低取所有 min_amount 的最小值,最高取所有 max_amount 的最大值。
例如通道 A 支持 10.00–100.00 MYR,通道 B 支持 20.00–2000.00 MYR,总体最低为 10.00 MYR、最高为 2000.00 MYR。请求金额严格低于最低值时,HTTP 200 响应如下:
{
"code": 40002,
"message_key": "error.amount_below_min",
"default_message": "amount below minimum",
"message": "amount below minimum (MYR 10.00)",
"data": null,
"request_id": "req_example_amount_below_min"
}
请求金额严格高于最高值时:
{
"code": 40003,
"message_key": "error.amount_above_max",
"default_message": "amount above maximum",
"message": "amount above maximum (MYR 2000.00)",
"data": null,
"request_id": "req_example_amount_above_max"
}
- 本地化只改变
message文案,币种与金额仍保留;程序使用code判断错误,不解析展示文案。 - 有通道未配置某侧边界时,该侧不限,不提示有限的总体边界。
- 汇总只取通道配置,不合并 API Key 或商户绑定限额;总体区间内仍须通过各通道、费率、银行、余额等校验。金额位于不同通道之间的区间空档时,继续返回原来的通道不匹配错误。
- 固定 Key、显式指定通道及已有正式订单重试保持原行为。API Key 自身限额校验、代付余额不足与内部错误优先沿用原错误,不保证所有创建失败都返回金额提示。
- 金额拒绝不保存新会话、不返回
payment_url,不创建正式订单或冻结资金。
通道维护错误与重试#
30002 / error.channel_maintenance 表示平台因通道维护拒绝本次新单,default_message 为 channel maintenance;它不是订单终态。自由匹配创建会排除维护通道,无合格候选时仍可能返回 30001 / error.channel_unavailable 或其他对应的校验错误,不保证所有维护场景都返回 30002。
收到维护错误时保留原 merchant_order_no,先查询是否已有正式订单;已有订单继续按原状态处理,不更换订单号重复创建。尚未生成正式订单的收银台会话可选择其他合格的 active 通道;若请求已指定 channel_code,不能通过修改该字段重试同一幂等创建请求。再次发送请求须生成新的 timestamp、nonce 和 sign,保持原创建业务参数一致。
发生错误时保存 code、message_key 和 request_id,使用原订单号查询结果。