bifu.us 菲律宾支付接入：原生 GCash 收款与代收代付解决方案（币付）

币付面向菲律宾市场提供原生 GCash 收款能力，并可按业务需要扩展至代收与代收代付模式，支持 H5 收银台与 API 对接，适用于电商、数字内容、平台型业务与跨境服务等多种场景。本文重点覆盖接入架构、交易链路、回调确认、对账与风控要点，帮助商户以更低的集成成本获得稳定、可控、可追溯的支付能力。

一、面向哪些业务更合适

电商与本地生活：订单支付、充值、会员订阅等标准收款链路。
数字内容与服务：虚拟商品、在线课程、工具类服务等即时交付型支付。
平台型业务：多商户、多角色结算需求，需要在交易层面实现更清晰的资金流与订单流管理。
跨境团队在菲展业：需要面向菲律宾用户提供更贴近本地习惯的 GCash 支付入口。

二、核心能力概览

原生 GCash 收款：围绕“创建订单 → 用户支付 → 状态确认 → 业务交付”的闭环设计交易流程。
H5 收银台：适配 Web 与 H5 场景，前端以跳转或拉起方式承接支付，降低多端集成复杂度。
API 对接模式：服务端发起交易请求，覆盖订单创建、状态查询、回调通知等关键链路。
代收与代收代付：在合规边界内按需开通，适用于平台型业务的资金流组织与分发，强调权限、风控与可追溯。
对账与审计友好：交易单号体系、状态机、通知记录、业务侧幂等控制，便于财务核对与问题定位。

三、费率与结算

以下为你已配置完成的费率表模块，包含 GCash 与 QRPH 的实施费率展示：

[rate-table type="all"]

四、接入架构建议：把“支付动作”和“交易确认”拆开

在菲律宾本地网络与终端环境下，链路稳定性不仅取决于用户端跳转是否成功，更取决于服务端对交易结果的确认策略。建议采用“双通道确认”，并明确主次关系：

用户端返回 return_url：用于引导用户回到业务页面，提升体验，但不作为最终记账依据。
服务端回调 notify_url：作为交易结果确认的主要依据，并结合订单状态查询进行兜底校验。

五、标准交易链路：收款

业务侧创建订单：生成全局唯一的业务订单号，锁定应付金额与币种，通常为 PHP。
向 bifu.us 发起创建支付请求：服务端提交订单信息、回调地址等参数，获取支付跳转地址或支付凭证。
用户完成支付：用户在 GCash 侧完成确认。
接收支付结果回调：业务服务端验签、落库、更新订单状态，只允许从“未支付/处理中”迁移到“成功/失败/关闭”等合法状态。
查询兜底：未收到回调或回调延迟时，按策略触发订单状态查询，最终以“可验证的成功状态”为准。
业务交付：只有在确认成功后才发放权益、出库、入账，避免灰产利用回跳伪造支付。

六、回调处理的三条硬规则

规则 1：只信任验签通过的回调。所有回调参数必须进行签名校验，验签失败一律拒绝处理并记录。
规则 2：回调必须幂等。同一笔支付可能重复通知，业务侧建议以“订单号 + 支付单号”作为幂等键，重复回调不得重复发货或重复入账。
规则 3：状态机必须单向收敛。状态变更要可追溯、可回放，禁止出现“成功 → 未支付”这类逆向迁移。

七、接口字段设计建议

为了便于不同系统保持一致性，建议围绕以下关键字段组织：

merchant_id：商户标识。
order_id：业务订单号，建议为业务系统主键或全局唯一编号。
amount：金额，建议使用整数分或 centavo，或明确统一的小数精度策略。
currency：币种，例如 PHP。
subject / body：商品或服务描述，用于对账与客服定位。
notify_url：服务端回调地址。
return_url：用户完成支付后的返回地址。
nonce / timestamp：防重放字段，按双方约定启用。
sign：签名字段，按约定算法与拼接规则生成。

{
  "merchant_id": "YOUR_MERCHANT_ID",
  "order_id": "ORDER_2026XXXXXX",
  "amount": 19900,
  "currency": "PHP",
  "subject": "Top-up / Order Payment",
  "notify_url": "https://yourdomain.com/pay/notify",
  "return_url": "https://yourdomain.com/pay/return",
  "nonce": "random_string",
  "timestamp": 1730000000,
  "sign": "signature_here"
}

八、代收代付落地要点：先把边界划清楚，再谈规模

代收与代收代付通常涉及更复杂的资金路径与合规要求。建议从一开始就把以下内容写进系统设计与业务流程：

角色与权限：平台、子商户、运营、财务、风控权限分离，并保留审计日志。
资金路径可解释：每笔资金的来源、去向、关联订单与业务理由必须可追溯。
资料管理：面向入驻方、收款方、出款方的信息完整性与一致性要求。
风险策略：限额、频控、黑名单、异常行为识别、争议处理与冻结机制。
对账闭环：订单流、支付流水、分账与结算流水三者必须能一一对应。

九、安全与风控：不要只做验签，要做全链路防护

密钥管理：密钥不落前端、不进日志；分环境管理；定期轮换。
签名与验签：严格按字段顺序与编码规则拼接；验签失败即拒绝。
来源校验：回调来源校验、回调域名固定化，降低伪造风险。
重放防护：对 nonce 与 timestamp 做校验，避免旧请求重复投递。
幂等与并发控制：同一订单并发回调时加锁，或基于数据库唯一约束处理。
异常监控：关注回调失败率、支付成功率、超时订单占比、重复通知占比、对账差异率。

十、上线建议：先稳再快

灰度策略：先在小流量业务或指定渠道上线，验证回调稳定性与对账闭环。
故障预案：用户返回失败、回调延迟、订单超时等场景的处理策略提前固化。
数据留痕：保存关键请求与回调摘要信息并注意脱敏，便于排查争议与对账差异。

十一、常见问题与处理原则

用户称已扣款但订单未成功：优先查询订单状态；若已成功但回调丢失，补发权益并记录；若未成功，按查询结果处理并进入工单。
回调重复导致重复发货：说明幂等没做好，必须使用幂等键与状态机保证只交付一次。
支付页面返回成功但后台未成功：用户返回不等于交易确认，必须以服务端回调或查询确认成功后再交付。

联系币付

如需获取接入资料、开通范围说明与对接支持，请联系：

Telegram：@Bifuapp
邮箱：[email protected]