支付通用规则
本地收单
支付通用规则
本页汇总 PayCools 支付接口的通用规则，目前包含参数格式约定（如手机号），以及收银台模式与 API 直连统一的回调通知规则。调用下单、收款、代付等接口时请遵循本页约定；后续更多通用的逻辑、参数与定义等规则也会持续沉淀在本页。
1
手机号格式
以下为各国家/地区手机号格式约定。PayCools 目前不校验手机号真实性（不会验证号码是否真实存在、是否已注册），但会校验格式（开头与位数）；格式不符会导致接口报错或被拒。
| 国家/地区 | 开头 | 总位数 | 说明 |
|---|---|---|---|
| 菲律宾 | 09 | 11 | 以 09 开头，共 11 位 |
| 印度尼西亚 | 08 | 10–13 | 以 08 开头，共 10–13 位 |
| 马来西亚 | 01 | 10–11 | 以 01 开头，共 10–11 位 |
| 泰国 | 06 / 08 / 09 | 10 | 以 06、08、09 开头，共 10 位 |
| 越南 | 03–09 | 10 | 以 03–09 开头（不含 0、1、2），共 10 位 |
| 俄罗斯 | 9 | 10 | 以 9 开头，共 10 位（不含国家码 7） |
| 沙特阿拉伯 | 05 | 10 | 以 05 开头，共 10 位 |
| 阿联酋 | 05 | 10 | 以 05 开头，共 10 位 |
| 卡塔尔 | 3 / 5 / 6 / 7 | 8 | 以 3、5、6、7 开头，共 8 位 |
| 科威特 | 41 / 5 / 6 / 9 | 8 | 以 41、5、6、9 开头，共 8 位 |
| 阿曼 | 7 / 9 | 8 | 以 7、9 开头，共 8 位 |
| 巴林 | 3 / 66 / 69 | 8 | 以 3、66、69 开头，共 8 位 |
| 墨西哥 | 52 | 12 | 固定以国家码 52 开头，第 3 位为 1–9，共 12 位 |
| 哥伦比亚 | 57 | 12 | 固定以国家码 57 开头，后接 10 位本地号码，共 12 位 |
| 阿根廷 | — | — | 系统暂未做格式校验，原样透传给渠道 |
2
回调通知规则
回调通知用于将交易结果同步给商户，收银台模式与 API 直连均遵循以下统一的投递与重试规则：
- 以 HTTP 状态码判定回调结果：PayCools 不解析回调响应体（
body）的内容；商户收到回调后返回HTTP 200即视为回调成功，PayCools 将不再重复回调；异常情况请返回非 200 状态码。 - 重试频率：回调失败（返回非 200）后，前 10 分钟每分钟通知一次，超过 10 分钟后每小时通知一次。
- 回调时限：超过 1 天的交易，不会再根据状态码自动回调。
需要说明的是，不同产品对「是否回调失败事件」的策略不同：收银台模式仅对成功的交易回调，API 直连对成功与失败均会回调，请以对应产品文档为准。
3
API 响应码
接口实时返回的 code 与 message，用于标识本次请求的处理结果。
通用接口响应码
| code | message | 介绍 |
|---|---|---|
| 10000 | Success | 请求成功 |
| 21000 | Server error, Please try again later. | 服务异常，请稍后重试 |
| 21001 | Request sign error | 请求验签失败 |
| 21002 | Request param error | 请求参数错误 |
| 21003 | Request appId error | appId 错误 |
| 21004 | Merchant is unavailable | 商户不可用 |
| 21005 | Merchant channel is unavailable | 商户渠道不可用 |
| 21006 | Merchant transaction not found | 商户交易不存在 |
| 21007 | Duplicate merchant order id | 商户订单号重复 |
| 21008 | Request timestamp error | 请求时间戳错误 |
| 21009 | Request timestamp error | 请求时间戳错误 |
| 21010 | The amount exceeds the limit | 金额超出限额 |
| 21011 | Network error | 网络异常 |
| 21012 | Request bank code error | 银行编码错误 |
| 21013 | Request wallet code error | 钱包编码错误 |
| 21014 | Merchant balance insufficient | 商户余额不足 |
| 21015 | Duplicate idempotencyId | 幂等号重复 |
| 21016 | Merchant ip forbidden | 商户 IP 不在白名单内 |
| 21017 | Merchant has not opened this national service | 商户未开通该国家/地区服务 |
| 21018 | Request transfer code error | transferCode 错误 |
| 21019 | Request pay method code error | payMethodCode 错误 |
| 21020 | Too many requests, please retry later. | 请求过于频繁，请稍后重试 |
| 21021 | Transaction Amount Invalid | 交易金额无效 |
| 21022 | Transaction Volume Limit | 交易笔数超限 |
| 21023 | Transaction create failed | 交易创建失败 |
| 21024 | Invalid access token | 访问令牌无效 |
| 21025 | Not allowed to cancel | 不允许取消 |
| 21026 | Customer Balance not enough | 用户余额不足 |
| 21027 | Transaction creation exceeds limit | 交易创建超出限制 |
| 21028 | Transaction already paid or closed | 交易已支付或已关闭 |
| 21050 | Business unit not found | 业务单元不存在 |
| 21051 | Business unit does not belong to this merchant | 业务单元不属于该商户 |
| 21056 | Cross region business is not allowed for this merchant | 该商户不允许跨区域业务 |
退款接口响应码
| code | message | 介绍 |
|---|---|---|
| 21401 | Refund is processing | 退款处理中 |
| 21402 | Not allowed to refund | 不允许退款 |
| 21403 | Transactions 60 days ago cannot initiate refunds | 超过 60 天的交易不可发起退款 |
| 21404 | The original transaction channel not support full refund | 原交易渠道不支持全额退款 |
| 21405 | The original transaction channel not support partial refund | 原交易渠道不支持部分退款 |
| 21406 | Refund amount invalid | 退款金额无效 |
| 21407 | MchRefundOrderId is repeat | 退款单号重复 |
| 21408 | The original transaction is not completed | 原交易未完成 |
| 21409 | The original transaction already exist pending refund | 原交易已存在处理中的退款 |
撤销接口响应码
| code | message | 介绍 |
|---|---|---|
| 21500 | Original transaction status is not success | 原交易状态不是成功 |
| 21501 | Cannot reverse | 无法撤销 |
| 21502 | Original transaction has been settled | 原交易已结算 |
| 21503 | Cannot void over the day | 不支持跨天撤销 |
| 21504 | Original transaction has been already voided | 原交易已撤销 |
| 21505 | Duplicate mchVoidOrderID detected. Please provide a unique mchvoidOrderID and retry. | 撤销单号重复，请换用唯一单号后重试 |
备注
完整提示码与说明请参考 API通用提示码。