菲律宾 GCash 支付接口对接指南：签约准备、API 调用流程、回调验签与稳定性保障｜币付 Bifu

GCash 是菲律宾主流电子钱包之一。对面向菲律宾用户的电商、线上娱乐、数字内容订阅、线下门店与跨境收款场景而言，接入 GCash 往往意味着更高的支付覆盖率与更顺畅的本地化体验。

本文从商户真实落地角度出发，给出一套可直接执行的对接路径：从签约与资料准备、接口联调、回调通知验签、订单状态一致性，到上线后的风控与稳定性建设。适用于技术团队、产品团队、运营对账团队协作推进的完整流程。

一、对接前准备：把“能付”变成“可持续稳定收款”

1）业务与合规准备清单

主体资质：公司主体信息、注册/营业文件、法人或负责人信息、业务介绍与网站/应用信息。
交易模型确认：线上/线下收款；支付形态（H5 收银台、应用内唤起、二维码等）；是否需要分账、多商户、多门店。
风控与合规要求：KYC/AML、退款政策、争议处理流程、敏感行业限制、交易限额与频控规则（以实际通道/机构要求为准）。
隐私与数据：最小化采集、加密存储、权限控制、日志脱敏与留存策略。

2）技术准备清单

接口密钥与鉴权方式：AppKey/Secret/证书或签名密钥；明确有效期、轮换机制与泄露应急预案。
回调地址：必须 HTTPS；建议主回调与备用回调分域名或分机房，降低单点风险。
IP 白名单：按通道要求配置出口 IP；准备灰度与切换策略，避免换 IP 断链。
订单号规则：商户订单号唯一且可追溯；建议引入幂等键避免重复下单。
对账数据：至少准备订单表、支付流水表、回调日志表、对账差异表四类核心数据结构。

二、整体架构与关键对象：先统一语言，沟通成本直接减半

1）典型系统角色

商户系统：业务后台、订单系统、APP 服务端。
币付 Bifu 聚合通道：统一接口/统一回调/统一对账/统一结算，支持多通道路由、风控与对账支撑。
通道侧：GCash（以及 QRPH 等）完成用户扣款与支付结果产出。
用户端：网页、APP、小程序等支付发起与支付确认载体。

2）关键字段建议（建议统一命名）

merchant_order_no：商户订单号（必须唯一）。
channel_trade_no：通道侧交易号（对账/申诉常用）。
amount / currency：金额与币种（常见 PHP）。
status：订单状态建议使用有限状态机（如 INIT、PENDING、SUCCESS、FAILED、CLOSED、REFUNDED）。
notify_id / notify_time：回调通知标识与时间（用于追踪与重放防护）。

三、核心对接流程：下单 → 引导支付 → 回调确认 → 状态兜底

流程 1：创建支付订单

商户服务端生成订单并落库，状态 INIT，确保订单号唯一。
调用币付 Bifu 支付接口创建交易，提交订单号、金额、最小必要用户信息、回调地址等。
获取支付指令（支付链接/支付凭证/二维码内容等）。
前端呈现支付，引导用户完成付款。

流程 2：支付结果通知（异步回调）

以异步回调为准，前端回跳不作为最终依据。
回调处理必做：验签与校验、幂等更新订单、记录日志。
按协议快速返回“已接收”响应，避免通道持续重试造成压力。

流程 3：主动查询兜底

触发条件：用户已付款但回调未到、前端显示不一致、支付中间态超过阈值。
做法：按订单号或交易号调用查询接口，以查询结果修正本地状态。
原则：回调为主、查询为辅；两者都必须幂等与留痕审计。

四、回调验签与安全：把“被通知”变成“可被信任的通知”

1）验签必做项

签名校验：按约定算法验签（HMAC / RSA 等）；字段排序与拼接规则必须一致。
金额与币种一致：回调金额必须等于下单金额，禁止回调驱动金额变更。
订单存在性：订单必须存在且属于当前商户；不合法直接拒绝并告警。
重放防护：利用 notify_id / nonce / 时间窗口去重，同一通知只处理一次。

2）传输与访问控制

强制 HTTPS：证书到期提前轮换，避免回调突然失败。
来源校验：仅允许可信来源访问回调接口，可结合 WAF/安全组/网关策略。
限流与熔断：回调入口按来源与路径限流，异常峰值保护主业务。
日志脱敏：手机号、邮箱、用户标识等仅保留必要片段，减少合规风险。

五、稳定性与工程化：线上问题通常不在“接口能不能调”

1）幂等：避免重复扣款、重复发货、重复入账

下单幂等：同一 merchant_order_no 重复提交时返回同一结果或明确拒绝重复创建。
回调幂等：同一 channel_trade_no 或 notify_id 多次回调只处理一次。
业务幂等：发货/开通会员/发放权益等动作必须在“已成功且未发放”条件下执行。

2）超时与重试：把不可控网络变成可控系统行为

合理设置连接与读取超时，避免线程/连接池被无限占用。
仅对可重试错误重试，采用指数退避并携带幂等键，避免雪崩。
回调入口轻处理：验签后入队，落库与发货异步消费，降低回调耗时与失败率。

3）监控与告警：把用户投诉前移为系统预警

关键指标：下单成功率、支付成功率、回调延迟分位数、回调失败率、查询兜底命中率、对账差异率。
关键日志：请求/响应摘要、签名校验结果、状态机变更记录、异常堆栈（脱敏）。
告警建议：回调连续失败、成功率突降、特定错误码突增、对账差异超阈值。

六、退款与对账：上线后最容易踩坑的两件事

1）退款处理要点

仅允许对 SUCCESS 状态订单发起退款。
退款单独生成 refund_no 并落库，关联原订单与通道交易号。
如需部分退款，需在签约与接口能力层面提前确认支持与限制。
退款同样以异步通知或查询为准，退款状态也要用状态机管理。
审计留痕：退款原因、操作人、审批链、原订单关联必须可追溯。

2）对账与结算要点

对账口径以通道侧账单或结算报表为基准；商户侧用订单流水与回调日志定位差异。
常见差异：成功未入账、入账未成功、金额不一致、重复回调导致重复处理、退款未闭环。
闭环建议：差异单生成 → 责任定位 → 修复动作（补单/冲正/人工核验）→ 归档。

七、上线验收清单：用检查项替代靠感觉

回调验签在压测与断网/重试场景下仍稳定。
订单状态机所有路径可验证、可回放、有审计日志。
下单、回调、发货、退款全部幂等覆盖。
回调丢失、重复回调、查询异常、通道维护、IP 变更均有预案。
监控告警具备阈值，报警可定位到订单与链路节点。
至少完成一次完整对账与差异修复演练。

八、费率与可用通道（实时更新）

币付 Bifu 支持菲律宾本地多通道聚合接入，可按业务场景灵活配置路由与成功率优化。常见渠道包括：GCash、QRPH，以及 Maya（原 PayMaya）、GrabPay、Coins.ph 等本地支付方式（具体以实际开通为准）。

币付 Bifu 实时费率表（包含 GCash 与 QRPH 等通道）：

[rate-table type="all"]

九、常见问题

1）前端回跳显示成功但回调没到，算成功吗？

不算。前端回跳只代表用户侧流程结束，不代表资金侧最终确认。必须以异步回调或主动查询确认 SUCCESS 后再发货或入账。

2）回调重复推送正常吗？

正常。支付通道为保证最终送达通常会重试推送。商户侧必须用 notify_id 或交易号做幂等处理，避免重复入账或重复发货。

3）为什么必须做主动查询兜底？

网络抖动、回调被拦截、证书问题、临时超时都可能导致回调丢失。没有查询兜底会出现大量“已扣款但订单未成功”的投诉与人工成本。

联系我们：币付 Bifu

如需对接支持、联调排查、回调验签与对账差异定位，可联系币付团队：

Telegram：@Bifuapp
邮箱：[email protected]