菲律宾三方支付直连方案：GCash 与 PayMaya（Maya）代收代付接口对接要点：风控与对账落地

面向菲律宾本地收款与出款场景，GCash 与 PayMaya（也称 Maya）的代收代付对接不止是“能支付、能出款”，更关键的是状态一致性、回调可靠性、对账可追溯、风控可管控、合规可解释。本文从业务边界、系统架构、接口关键点、回调一致性、代付风控、对账闭环与上线验收清单，给出可执行的直连接入落地要点，适用于电商、数字内容、订阅、游戏点卡、线下服务等需要本地钱包收付能力的商户。

实时费率表（币付 Bifu｜含 GCash、QRPH 等通道）

[rate-table type="all"]

一、先把业务范围定清：边界决定实现复杂度

启动技术对接前，建议把业务动作拆清并形成可验收的范围清单，避免上线后“补洞”导致重复改造：

代收（Collection / Pay-in）：用户发起支付、支付结果查询、失败原因处理、超时关闭与订单释放。
退款（Refund）：全额/部分退款、重复退款防重、退款状态跟踪与对账确认。
代付（Disbursement / Pay-out）：单笔出款、批量出款、失败重试策略、失败原因码治理、人工复核与审批链。
交易查询与对账：订单维度查询、流水维度查询、日/周期对账文件处理、差错处理流程。

若存在多币种结算、分账、平台型多子商户、线下聚合码等复杂场景，建议在方案阶段明确是否纳入本期，避免拖慢主链路交付。

二、直连的核心对象：订单、支付单、渠道流水必须一一对应

直连场景里最常见的事故不是“接口报错”，而是“账务对不上”。建议从数据模型层把三件事锁死：

商户订单（Order）：业务侧唯一，决定发货/开通服务。
支付单/出款单（Payment / Payout）：网关侧唯一，承载状态机与重试幂等。
渠道流水（Channel Transaction）：渠道侧唯一，决定对账与财务入账。

强建议：任何回调、查询、对账解析，都要能从渠道流水号回落到支付单/出款单，再回落到商户订单。链路缺一不可。

三、系统架构建议：把“不可靠”隔离在网关层

GCash、PayMaya 等渠道结果具备异步特征：用户端显示成功，不等于你服务端已确认成功。架构上建议将不确定性收敛在支付网关层：

支付网关服务：下单、签名验签、回调处理、状态机、幂等、防重、重试、告警。
订单服务：只接收“已确认成功/已确认失败/已关闭”的终态事件，不直接依赖渠道回调。
消息队列/事件总线：回调到达先落库再投递事件，保证可追溯与可重放。
对账服务：独立处理对账文件或对账接口，负责差错单生成与工单流转。

这样做的收益很直接：回调丢失、延迟、重复、乱序不会污染订单业务逻辑，可维护性显著提升。

四、接口对接必踩点：幂等、签名、超时、状态映射

1）幂等：防重的第一优先级

无论代收还是代付，都必须具备幂等能力：

请求幂等：同一业务请求重复提交，返回同一结果或同一支付单，避免重复扣款/重复出款。
回调幂等：同一渠道通知多次到达，只做一次状态推进与一次业务通知。
退款幂等：同一退款指令重复触发，不重复退。

落地做法：以“商户侧请求号/幂等键 + 业务类型”建立唯一约束，状态推进使用版本号/乐观锁避免并发踩踏。

2）签名与验签：不要只看能跑通

统一签名算法与字段规则：字段排序、空值处理、编码方式必须明确。
验签失败进入隔离队列，禁止直接丢弃；保留原始报文便于排查与审计。
敏感字段在传输与存储层做最小化与脱敏，降低合规与安全暴露面。

3）超时与重试：把可靠到达当作系统职责

下单超时：不等于失败，必须走查询确认或等待回调，避免误关闭。
出款超时：不允许自动二次发起“新出款”，优先用原请求号查询渠道状态。
重试策略：指数退避 + 最大重试次数 + 人工介入阈值，避免雪崩与重复付款风险。

4）状态映射：统一终态口径

建议网关内部维护清晰状态机，例如：

处理中：已提交渠道，等待回调或查询确认。
成功：已验签确认成功，允许发货/开通服务。
失败：已确认失败，允许用户重试或更换方式。
已关闭/已过期：订单不再接受支付，避免“支付成功但订单已关闭”的纠纷。

五、回调与一致性：目标是最终一致且可证明

回调系统的目标不是“立刻更新”，而是“最终一定更新且有证据链”。建议配置三道保障：

回调落库：收到回调先持久化原始内容与解析结果，再推进状态。
主动查询补偿：对处于处理中超过阈值的交易，计划任务触发查询补偿。
告警与工单：验签失败、状态长时间不终结、对账差错必须可告警与可追踪。

六、代付专项：比代收更需要风控、审批、证据链

代付风险更高，建议默认强管控：

出款前校验：余额/额度、收款人信息、黑名单/高风险识别、同账号频次限制。
审批策略：高金额或高风险命中走人工复核；支持分级审批与留痕。
失败原因治理：失败码分为可重试/不可重试/需人工处理，避免无脑重试。
证据链：出款申请、审核记录、渠道返回、回调与查询结果全量可追溯，便于争议处理。

七、对账与财务落地：能对上账才算交付

对账建议至少覆盖三类差错：

我方成功、渠道未成功：多由回调误判或状态推进缺陷导致，需阻断发货/服务开通并回滚处理。
我方未成功、渠道成功：常见于回调丢失/延迟，必须依赖补偿查询与对账纠偏。
金额不一致：多见于部分退款、手续费口径差异、币种与精度处理问题，需要明确财务口径与字段精度。

建议对账产出差错单并形成固定闭环：定位原因 → 修复数据 → 风控复盘 → 规则迭代。

八、合规与风控：不仅要过审，更要可持续运营

KYC/AML 配合：按业务类型与风险等级设置必要的信息采集与留存策略，确保可审计。
交易监控：异常频次、异常金额、异常设备/网络特征、异常地理特征等维度的实时或准实时监控。
限额与分层：新用户、低信任用户、异常用户分层限额；出款应更严格。
数据最小化：仅收集必要数据，日志与报表脱敏，降低合规与安全暴露面。

九、上线流程建议：可回滚、可观测、可解释

联调阶段：覆盖成功、失败、超时、回调重复、回调乱序、验签失败等关键用例。
灰度阶段：小流量放量，监控成功率、平均耗时、回调到达率、补偿查询比例与差错率。
全量阶段：持续优化状态机与风控规则；对账差错必须有固定 SOP。

监控建议至少包含：渠道请求成功率、回调成功率、终态达成时延、补偿查询命中率、差错单数量与处理时长。

十、币付 Bifu 的落地协作：把直连从“跑通”提升到“可运营”

币付 Bifu 面向菲律宾本地支付场景，帮助商户把关键能力一次性做扎实：幂等与状态机、回调可靠性、对账闭环、风险治理与上线验收清单。除 GCash、PayMaya（Maya）外，也可根据业务需要扩展到 QRPH、GrabPay、Coins.ph 等本地主流支付方式，实现统一接口、统一回调、统一对账与统一结算管理。

联系我们（币付 Bifu）

客服 Telegram：@Bifuapp

客服邮箱：[email protected]