币付 Bifu GCash 支付 API 集成指南：通道接入、安全与上线验收要点

在菲律宾接入 GCash，真正决定能否长期稳定运行的，不是“能不能发起支付”，而是链路稳定性、回调一致性、幂等与状态机、风控边界、对账闭环是否工程化落地。本文给出一套可直接执行的接入结构与验收清单，帮助技术与运营团队把支付做成可观测、可追溯、可审计的系统能力。

一、适用对象与典型场景

商户/平台方：需要在菲律宾提供 GCash 本地收款能力。
技术团队：负责支付下单、回调处理、订单状态、对账与运维监控。
运营/财务：关注成功率、入账一致性、退款与差错处理、结算口径。

典型场景：电商下单支付、数字内容付费、会员订阅、游戏/应用内充值、在线服务预约、线下引导线上付款等；并可按需扩展到 QRPH 等本地扫码链路，统一回调与对账口径。

二、对接前准备清单

业务资料：经营主体信息、业务类型说明、产品/服务描述、退款与售后规则、风控策略口径。
回调与域名：公网可达的 HTTPS 回调地址、独立支付域名、证书链完整。
订单系统：订单号全局唯一；支持幂等写入；订单状态更新有明确状态机。
日志与监控：请求链路日志、回调日志、告警（成功率波动/回调堆积/验签失败/接口超时）。
安全治理：密钥不落前端、不硬编码；支持轮换；必要时启用 IP 白名单或来源校验。

三、推荐架构：状态机 + 异步事件 + 对账兜底

把支付当作“订单状态机 + 异步事件驱动”。核心原则：

回调为主：支付结果以异步回调驱动状态更新。
查询为辅：用于回调丢失、延迟、投诉场景的兜底核验。
对账兜底：以对账文件/结算报表作为财务最终确认，差错进入工单化处理。

建议订单状态最少覆盖：

CREATED：订单创建并落库成功。
PENDING：已发起支付，等待用户完成或渠道确认。
PAID：支付成功，业务可发货/发权益。
FAILED：明确失败，可提示重试。
CLOSED：超时关闭或主动关闭，不可再支付。
REFUNDING / REFUNDED：退款中 / 已退款（如开通）。

四、核心对接流程拆解

1）发起支付：下单与幂等

订单号：全局唯一且可追溯，建议包含时间与业务前缀。
幂等键：同一订单重复请求不得重复扣款或重复创建新支付单。
金额与格式：金额精度、币种字段、描述长度与字符集统一规范化。
可观测性：每次请求生成 request_id，贯穿日志、追踪与排障。

2）支付承接：跳转/收银台/二维码

前端负责展示与引导，不以前端回传作为最终支付成功依据。
用户中断可恢复：允许用户返回后通过订单查询或等待回调恢复状态。
提示策略：支付完成后提示“以系统到账为准”，避免截图争议。

3）异步回调：最关键的一跳

回调处理建议做到“四个必做”：验签、幂等、原子更新、快速响应。

验签：严格校验签名，防篡改与伪造。
幂等：同一订单多次回调只允许生效一次，重复通知是常态。
原子更新：订单状态更新与资金流水落库建议同一事务，避免状态成功但流水缺失。
快速响应：先落库，再异步发货/发权益/通知，避免回调超时导致重复回调放大。

4）主动查询：兜底与自助排查

以商户订单号为主键，渠道流水号为辅助索引。
PENDING 超过阈值仍未回调，触发定时补偿查询并更新状态。
对查询做限流与频控，避免异常流量拖垮系统。

五、安全设计要点

签名一致性：字段顺序、编码方式、空值处理必须严格一致。
回放防护：引入 nonce 与时间戳；服务端短期去重或落库校验。
来源控制：能做 IP 白名单就启用；不能做也必须严格验签 + 幂等。
密钥治理：密钥不出现在前端与客户端包；使用环境变量或密钥管理；支持轮换。
日志脱敏：禁止明文记录密钥与敏感隐私字段，必要信息做掩码与分级存储。

六、对账与结算：从支付成功到财务可确认

支付成功只是业务状态，财务确认需要对账闭环。建议建立三套机制：

订单对账：订单状态与渠道状态一致。
资金对账：入账金额、手续费、净额与结算周期一致。
差错处理：对账差异进入工单流程，明确原因、补偿策略、审计留痕。

建议为客服/财务提供订单自助查询入口：输入商户订单号即可看到链路摘要、回调次数、最近一次查询时间、关键字段校验结果，显著降低沟通成本。

七、费率与结算说明

以下为币付已配置好的费率表展示代码，包含 GCash 与 QRPH。实际费率、结算周期与特殊规则以开通时协议为准。

[rate-table type="all"]

八、上线验收清单

金额、币种、订单号、描述在下单/回调/查询/对账全链路一致。
回调验签通过率 100%，签名异常可快速定位到字段顺序、编码或空值处理。
幂等验证通过：重复回调、重复查询、重复下单不产生重复记账或重复发货。
异常覆盖：超时、断网、用户中断、处理中、失败重试、回调延迟均有策略。
补偿机制可用：PENDING 超时触发查询补偿，且有频控与告警。
监控告警完善：成功率波动、回调堆积、验签失败、接口超时可定位可追踪。
密钥与权限合格：最小权限、可轮换、日志脱敏符合要求。

九、常见问题与排查路径

1）回调收不到

确认回调地址公网可达，HTTPS 证书链完整，WAF/防火墙未拦截。
检查回调处理是否超时：先落库再异步，避免重任务阻塞。
完善回调接收日志：记录请求头、请求体摘要、验签结果、返回码与耗时。

2）验签失败

核对签名串拼接规则：字段顺序、URL 编码、空值字段参与规则、大小写与字符集。
核对金额格式与精度：小数位、去尾零、字符串化规则必须统一。
避免“解析后重组”导致字段变化：优先使用原始回调内容计算验签。

3）用户显示已支付但系统未更新

以回调与查询结果为准，不以截图或前端状态为准。
对 PENDING 启用查询补偿与人工复核入口，确保可快速闭环。

十、接入咨询与支持

如需开通币付 Bifu 的 GCash 收款能力、获取对接资料与技术支持，请联系：

Telegram：@Bifuapp
Email：[email protected]

为加速评估与对接，建议同时提供：业务类型、预估日交易量与客单价区间、站点或应用形态、期望支付承接方式、回调域名、技术对接人信息。