SMARTPAY

GCash 支付对接常见错误码大全:签名失败、超时、余额不足怎么排查(2026)

GCash 支付对接里最耗时间的往往不是搭链路,而是遇到一个陌生错误码却不知道从哪查起。本文把签名失败、超时、余额不足等高频错误码按类型梳理清楚,配真实 curl 调试示例,帮你把"猜错误"变成"按图索骥"。

一、GCash 对接为什么总卡在错误码上

GCash 支付对接走通"下单—支付—回调—对账"这条链路本身不难,真正拖慢联调进度的,是拿到一个错误码却不知道该往哪个方向排查。同一类错误在不同网关文档里叫法不一样,商户技术团队经常靠猜、靠试错定位问题,一来一回浪费好几天联调时间。把常见错误码按类型梳理清楚、配好排查步骤,能把联调周期明显缩短。

二、错误码怎么分类:先分清是谁的错

遇到错误码,第一步不是翻文档,是先判断错误发生在哪一层:

  • 参数层:请求体字段缺失、格式不对、类型不匹配
  • 签名层:验签失败,通常是拼串、编码或密钥使用有问题
  • 网络层:请求超时、连接被拒绝、出口 IP 未加白
  • 业务状态层:订单已存在、订单已过期、余额不足、风控拦截

分清层级才能决定去查代码、查网络还是查商户资料。很多联调卡壳,都是把签名层的问题当参数层排查,越查越乱。

三、GCash 支付对接常见错误码清单

错误码含义常见原因排查建议
SIGN_ERROR签名验证失败参数拼接顺序错、字符编码不一致、密钥版本用错逐字段核对签名原串,确认密钥没有多余空格或换行
PARAM_MISSING必填参数缺失漏传 merchant_id、notify_url 等字段用最小可运行请求体逐个字段补全测试
PARAM_INVALID参数格式错误金额格式不对、订单号含非法字符核对每个字段的数据类型与长度限制
MERCHANT_NOT_FOUND商户号不存在或未激活商户号填错、沙箱号打到生产环境确认请求域名与商户号所属环境一致
ORDER_DUPLICATE订单号重复同一个 out_trade_no 重复提交每次下单生成唯一订单号,失败重试用新流水号
ORDER_EXPIRED订单已过期支付页面停留过久或系统时间不同步核对服务器时间与标准时间是否对齐
TIMEOUT请求超时网络链路不稳定、出口 IP 被限流加超时重试与退避机制,确认出口 IP 已加白
INSUFFICIENT_BALANCE用户余额不足用户钱包余额不够支付本次金额属于用户侧问题,引导切换支付方式
CALLBACK_TIMEOUT回调通知超时商户服务器处理回调过慢,未按时响应回调接口先落库再异步处理,尽快返回确认应答
RISK_REJECTED风控拦截短时高频下单、设备异常等触发反欺诈规则联系网关核实风控策略,必要时申请白名单

四、错误排查实战:验签失败、超时与余额不足

验签失败(SIGN_ERROR)怎么一步步排查

验签失败是联调阶段出现频率最高的错误,建议按顺序核查:

  1. 参数字典序:参与签名的字段要按 key 的字典序排列,不能按业务顺序随意排列
  2. 空值处理:值为空或 null 的字段,剔除还是保留要与网关约定一致
  3. 编码时机:一般先拼串签名、再做 URL Encode,顺序反了签名必错
  4. 密钥版本:密钥更换过渡期最容易验签失败,确认用的是当前生效密钥
  5. 隐藏字符:复制密钥时最容易带进换行符或空格,建议打印密钥长度核对

超时与余额不足:两种最容易被混淆的错误

TIMEOUT 和 INSUFFICIENT_BALANCE 表面上都是"支付没成功",处理方式却完全不同。超时是链路问题,商户侧该做的是重试兜底与主动查询,而不是直接判定失败;余额不足是用户侧问题,商户侧能做的只是给出清晰提示和备用支付方式引导。混淆两者最常见的后果,是把本该重试的超时订单直接标记失败,导致真实到账的钱和订单状态对不上,后续对账出现差错。

真实调试示例:用 curl 复现并定位问题

遇到验签失败,先用最小化请求复现问题,再逐步加参数,比对照整份文档排查快得多:

最小化调试请求

curl -X POST https://api.yourgateway.com/v1/gcash/order/create \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_id": "M100086",
    "out_trade_no": "TEST20260928001",
    "amount": "100.00",
    "currency": "PHP",
    "notify_url": "https://yourshop.com/callback",
    "sign": "替换为本地计算的签名"
  }'

拿到响应后先看 HTTP 状态码,再看响应体里的错误码字段。如果返回 SIGN_ERROR,把本地签名计算过程单独抽出来,打印参与签名的原始字符串,和网关文档给的示例逐字符比对,通常很快能定位到底是哪个环节出了问题。

五、通过 SMARTPAY 排查这些问题

自己排查错误码最耗时的部分,往往不是找到原因,而是不确定"这个错误码到底代表什么"。持牌四方网关的价值之一,是有专职联调工程师陪跑,遇到陌生错误码可以直接对照内部案例库定位,而不是从零猜。可先读 GCash 收款 API 对接教程 了解整体接入流程,再结合 GCash 商户回调 处理规范排查回调类问题;通用联调思路也可参考 菲律宾支付 API 怎么对接。

SMARTPAY 是持 BSP OPS/EMI 牌照的独立支付网关,提供 GCash 等通道的对接与联调排查支持,并非 GCash 官方,GCash 为其商标持有方所有。

六、常见问题

遇到没在清单里的错误码怎么办?

先按参数层、签名层、网络层、业务状态层四类判断归属,再联系网关技术支持确认具体含义,不同网关对同一类问题的命名可能不一样。

验签一直失败,但代码逻辑看着没问题怎么办?

大概率是密钥或字符编码的问题,建议打印原始签名串逐字符核对,而不是只反复检查代码逻辑。

超时之后要不要用新订单号重试?

不建议。应该先用原订单号做状态查询,确认没有支付成功,再决定是否需要让用户重新发起支付。

回调一直收不到怎么排查?

先检查回调地址能否被公网访问、证书是否有效,同时做主动查询兜底,不要完全依赖回调通知。

沙箱测试通过,上生产就报错正常吗?

比较常见,多数是生产密钥或商户号没切换、出口 IP 没有在生产环境重新加白导致的。

要不要自己维护一份错误码对照表?

建议维护。联调阶段就把遇到的错误码、原因和处理办法记录下来,后续接口升级或排查同类问题时能省下大量时间。

七、快速接入

想要一套接口就拿到完整的错误排查支持与联调陪跑,欢迎联系 SMARTPAY:📩 [email protected] | Telegram @LouisSMARTPAY

相关推荐