币付 Bifu：菲律宾 GCash 原生支付代收代付接入技术方案与运维要点

面向在菲律宾开展业务的商户，GCash 原生支付的代收与代付能力，直接影响收款转化、资金周转、风控合规与对账效率。本文从业务流程、接口设计、回调验签、幂等与重试、对账闭环、风控与运维监控等维度，给出一套可落地的接入方案，帮助团队用工程化方式把支付做稳。

适用对象

电商、游戏、线上娱乐、订阅服务、本地生活、跨境数字服务等需要 GCash 收款与出款能力的商户技术团队、产品与运营团队、财务对账团队。

一 接入目标与范围

在支付项目中，能付只是起点，稳定可控、账务闭环、合规可解释才是交付标准。GCash 原生支付代收代付接入通常包含以下目标：

• 代收：用户使用 GCash 完成支付，商户获得可核验、可回放的支付结果，订单状态可追溯。

• 代付：商户向用户钱包发起付款，适用于退款、佣金、奖励、提现等场景，结果可回调，失败可重试且可解释。

• 对账闭环：交易流水、手续费、退款、冲正等在商户侧形成统一账本口径，差错可定位、可处理。

• 风控合规：身份与交易风险可控，异常行为可拦截，材料与链路可审计。

二 系统角色与推荐架构

建议把支付集成拆成业务系统与支付域服务两层，避免支付逻辑散落在各业务模块，降低后续扩展成本：

• 商户业务系统：下单、发货或发放、退款申请、用户中心等。

• 商户支付域服务：订单创建、签名、回调处理、状态机、对账、风控、告警与报表。

• 币付 Bifu：作为对接与交易处理通道，承接代收与代付请求并交付回调结果。

• GCash：用户侧支付与钱包资金处理。

关键原则：所有资金相关状态以异步最终一致为目标设计，任何一步都必须可重试、可幂等、可审计。

三 代收流程设计

3.1 订单创建

创建支付订单时必须一次性确定清晰的业务口径，避免后续改金额、改商品、改用户造成不可审计：

• merchant_order_id：商户侧唯一订单号，要求全局唯一，建议可读但不可猜。

• amount 与 currency：金额与币种，金额建议使用最小货币单位的整数存储，避免浮点误差。

• subject 与 description：交易摘要，便于内部识别与对账。

• notify_url：服务端回调地址，仅服务端可达。

• return_url：前端跳转地址，仅用于体验，不作为最终结果依据。

• client_ip 与 device_info：可选字段，用于风控与审计。

3.2 用户完成支付与结果确认

支付成功的唯一可信信号来自服务端回调或服务端查询结果，而不是前端跳转。原因包括网络中断、用户强退、浏览器拦截、跳转伪造等。

• 回调优先：收到回调后更新订单状态并落库。

• 查询兜底：对长时间未回调或疑似丢回调订单触发服务端查询补偿。

• 状态机驱动：避免直接写成功失败，使用可扩展状态集合。

四 代付流程设计

4.1 代付请求发起

代付是高风险能力，必须把资金安全放在第一位。建议代付在商户侧必须满足权限校验、额度校验、风控校验，必要时加入人工复核后再触发：

• merchant_payout_id：代付单号，全局唯一。

• recipient：收款人标识，例如钱包账号或用户标识，按对接规范提供。

• amount：出款金额。

• purpose：出款用途，例如退款、佣金、奖励、提现。

• notify_url：代付结果回调地址。

4.2 代付结果处理

代付结果同样遵循回调为主、查询兜底。尤其是出款失败场景必须可解释、可定位，并能驱动后续动作：

• 失败分类：参数类、余额或额度类、风控拦截类、通道超时类、未知状态类。

• 重试策略：仅对可重试失败重试，对不可重试失败直接终止并产出可读原因。

五 订单状态机设计

状态机是支付稳定性的地基。建议统一管理状态与事件，避免分支逻辑蔓延。示例状态如下：

• INIT：订单初始化。

• PENDING：已创建，等待支付或处理中。

• SUCCESS：成功，资金结果已确认。

• FAILED：失败，已获得明确失败原因。

• UNKNOWN：不确定，需要查询补偿。

• CLOSED：已关闭或超时关闭。

• REFUNDING：退款处理中。

• REFUNDED：已退款。

强约束：任何终态一旦写入必须禁止回滚，除非通过可审计的冲正或补单机制修正。

六 回调安全与幂等基线

回调处理必须满足可验证、可幂等、可重放保护、可审计。

6.1 验签与来源校验

• HTTPS：回调地址必须使用 HTTPS。

• 签名校验：对回调参数进行签名验证，拒绝未通过验签请求。

• 重放保护：校验时间戳与随机串，并在商户侧做短期去重缓存。

• 白名单：如支持来源限制，可按 IP 或网段做限制，减少攻击面。

6.2 幂等处理

回调重复发送是常态，不是异常。必须保证同一订单同一结果多次到达时不会重复发货、重复入账、重复发放权益：

• 幂等键：merchant_order_id 或 merchant_payout_id 加通道流水号。

• 原子落库：更新订单状态与写入流水尽量在同一事务内完成，或使用事件表保证最终一致。

七 对账与差错处理闭环

支付要可运营就必须可对账。建议商户侧至少具备以下能力：

• 交易流水表：记录通道流水号、商户订单号、金额、状态、创建与更新事件、回调原文摘要。

• 对账任务：按固定频率拉取或接收对账数据后完成逐笔核对。

• 差错单：对本地成功通道失败、本地失败通道成功、金额不一致、状态未知等生成差错单并闭环处理。

• 审计留痕：差错处理记录操作人、操作时间、处理原因与证据链，包括日志、回调、查询结果。

八 风控与合规要点

• KYC 口径：出款给用户前必须明确用户身份与账号绑定关系，降低盗用与洗钱风险。

• 交易监控：对高频小额密集、异常地域或设备、失败率突增、短时大量出款等建立规则与告警。

• 黑名单与限额：对账户、设备、IP、收款标识建立可配置策略，支持封禁、限额、人工复核。

• 数据最小化：只采集完成交易必要数据，敏感字段脱敏存储，访问审计可追踪。

九 稳定性工程

支付失败常见原因不是逻辑错误，而是网络与系统现实。建议把稳定性工程当作交付核心：

• 超时控制：客户端与服务端统一超时策略，避免无穷等待与资源占用。

• 重试分级：网络超时与未知状态可重试，参数错误与风控拒绝不可重试。

• 补偿机制：对 UNKNOWN 状态订单做定时查询与状态纠偏。

• 关键指标：成功率、回调延迟、未知状态占比、重复回调占比、代付失败率、对账差错率。

• 告警策略：阈值告警加异常波动告警，避免慢性故障被忽视。

十 上线前检查清单

• 代收与代付订单号规则已确定，保证全局唯一且不可重复。

• 回调验签通过，重复回调不会造成重复发货、重复入账、重复发放。

• 状态机完整，UNKNOWN 有查询补偿，终态不可回滚。

• 日志可追溯，能定位每笔订单的请求、回调、查询、落库与业务动作。

• 对账能力可用，能发现差错、生成差错单并闭环处理且留痕。

• 风控策略已落地，限额、黑名单、异常监控与人工复核流程明确。

• 告警已配置，成功率、回调延迟、未知状态占比、代付失败率等可监控。

十一 费率说明

[rate-table type="all"]

十二 币付对接与支持

为保证对接效率，建议在技术对接时准备业务场景说明、订单字段定义、回调处理逻辑、对账口径、风控策略初稿与上线计划。

• Telegram：@Bifuapp

• Email：[email protected]