菲律宾支付通道接入指南：支持 GCash 与 QRPH 聚合支付的快捷对接方案（币付）

面向在菲律宾开展业务的商户与技术团队，本文梳理 GCash 与 QRPH（QR Ph） 等本地支付/聚合支付接入的关键环节：从业务场景拆解、对接流程设计、支付结果回调、对账与风控，到上线验收清单与常见问题处理，帮助你以更低成本、更稳定的方式完成支付通道落地。

一、为什么要同时接入 GCash 与 QRPH 聚合支付

菲律宾市场用户支付偏好分散，仅接入单一渠道往往覆盖不足。将 GCash 与 QRPH 聚合码（以及可扩展到 Maya、GrabPay、Coins.ph 等本地方式）组合接入，通常能带来更好的支付成功率与运营弹性：

覆盖更广：既满足偏好电子钱包的用户，也兼顾扫码聚合的场景。
体验更稳：当某一渠道波动时，可按策略切换与分流，减少交易中断带来的损失。
运营更灵活：可按产品线、地区、金额区间、风险等级配置不同通道策略。
对账更清晰：统一订单号、统一回调与统一对账口径，降低财务与客服成本。

二、币付支付通道适用场景

币付面向需要稳定收款与清晰结算链路的业务场景，常见包括：

电商与本地生活：下单支付、到店扫码、分段支付、退款与售后。
数字服务：会员订阅、充值、虚拟商品、内容付费。
企业收款：批量收款、付款凭证留存、订单状态同步。
平台型业务：多商户、多门店管理，分账或结算报表导出需求。

三、标准接入架构：从下单到入账的完整闭环

建议把支付对接视为一条完整链路，而不是“只要能唤起支付就行”。一套可长期稳定运营的闭环通常包含以下模块：

1）统一下单：创建订单

商户系统生成唯一订单号，不可复用，记录金额、币种、商品/服务信息、用户标识、来源渠道等字段。
调用币付统一接口创建支付单，返回支付凭证，例如跳转链接、二维码内容、支付令牌等。

2）唤起支付：支付发起

H5、APP、PC 根据终端类型选择跳转或展示二维码。
聚合支付场景建议提供“多方式选择页”，并将用户选择写回订单扩展字段，便于统计分析。

3）异步回调：Webhook 通知

支付成功与否以服务端异步回调为准，前端返回仅作体验提示。
回调必须做验签与幂等处理，并更新订单状态机：待支付、支付中、成功、失败、关闭、退款中、已退款。

4）订单查询与补单：Query 与 Repair

对超时或网络异常订单，使用查询接口拉取真实状态。
建立补单任务，对长时间未终态订单定期重查，降低漏单概率。

5）对账与结算：Reconciliation 与 Settlement

通过交易明细、结算明细进行核对，确保“订单—支付单—入账记录”三者一致。
退款需具备完整追踪链路：退款请求、退款结果回调、对账核销。

四、接入实现要点：开发与运维必须做对的细节

1）回调验签与安全策略

验签必做：校验签名、时间戳、防重放参数，拒绝伪造通知。
白名单与限流：对回调入口配置来源校验、限流与防护策略，降低恶意刷请求风险。
敏感信息保护：密钥与令牌仅保存在服务端安全存储中，不出现在前端代码与明文日志里。

2）幂等与状态机

同一订单可能收到多次通知，必须以幂等键与终态判断避免重复入账。
订单状态变更建议使用单向流转状态机，避免回滚造成数据错乱。

3）超时与异常处理

为每一笔支付定义合理的有效期与超时策略，到期自动关闭或提示用户重新发起。
对“已扣款但未回调”等极端情况，依赖查询补单与人工复核流程兜底。

4）日志与可观测性

记录关键字段：订单号、支付单号、渠道类型（GCash / QRPH / Maya / GrabPay / Coins.ph 等）、金额、状态、回调次数、错误码、请求耗时。
建立告警：成功率异常、回调失败率上升、接口耗时飙升、重复通知激增等。

五、聚合支付策略：让更多方式转化为更高成功率

聚合支付不是把入口堆在一起，而是用策略提升效率与成功率。建议从三方面入手：

智能排序：按用户历史偏好、终端类型、地域、金额区间设置默认方式排序。
分流规则：当单一渠道失败率上升时，自动降低权重或切换备用通道。
体验一致：统一支付结果页与订单状态提示，避免不同渠道带来的体验割裂。

六、实时费率参考

以下为币付后台可展示的 GCash + QRPH 实时费率表（示例组件）：

[rate-table type="all"]

七、上线验收清单

订单号规则唯一、不可预测、不可复用；金额与币种校验完备。
回调验签通过；回调接口具备幂等；重复通知不会重复入账。
前端仅做展示，最终以服务端回调与查询为准；异常路径有清晰提示。
已实现订单查询与补单任务；超时订单可自动收口到终态。
已实现退款流程（如业务需要）；退款结果可回调或可查询核对。
日志字段齐全；关键指标可监控；异常阈值有告警。
生产环境密钥安全存储；权限最小化；敏感信息不落明文日志。

八、常见问题与排查方向

1）用户显示支付成功，但系统订单未变更

优先检查回调是否到达：网络、白名单、防护策略、限流策略。
检查验签失败原因：密钥配置、签名串拼接顺序、编码方式。
启用查询补单：确认支付单真实状态，避免漏单。

2）回调重复导致重复发货或重复加余额

补齐幂等：以订单号或支付单号作为幂等键，只允许首次入账成功。
对已终态订单直接返回成功响应，减少对方重试。

3）聚合入口很多，但成功率不升反降

检查默认排序与引导文案是否清晰，避免用户选择成本过高。
对异常渠道做降权分流；统计失败原因分布，例如超时、取消、余额不足、网络问题。

九、联系币付：获取对接支持

如需对接咨询、技术接入协助或测试排查支持，可通过以下方式联系币付团队：

Telegram：@Bifuapp
邮箱：[email protected]