菲律宾支付接口集成方案：GCash 与 Maya 快速接入、回调验签与对账结算

在菲律宾本地收款场景中，GCash 与 Maya 是高频支付方式。企业在自建收银台、App 内支付、H5 收款、线上线下融合（扫码/链接支付）等场景里，往往同时面临“接入快、稳定性高、对账清晰、风控可控”的综合要求。本文从技术对接与运营落地两个维度，给出可直接执行的集成方案与上线清单，帮助商户更快完成支付通道建设。

一、接入目标与适用场景

电商/独立站：下单收款、支付状态同步、退款、部分退款、对账结算。
数字服务：会员订阅、充值、订单重复支付防护、异步回调一致性。
线下收款：二维码/支付链接/收银台聚合，提升收银效率与成功率。
平台型业务：分账/多商户管理、代付到个人或商户账户、交易风控与争议处理。

二、推荐的系统架构

建议采用“业务系统 + 支付网关 + 回调中心 + 账务/对账模块”的拆分架构，以降低耦合、提升可观测性：

业务服务（Merchant Server）：生成订单、发起支付、展示支付页/二维码、处理业务发货逻辑。
币付支付网关（Bifu Gateway）：统一封装 GCash/Maya 的差异，提供标准化下单、查询、退款、代付等能力。
回调中心（Webhook Receiver）：验签、幂等、重放保护、落库、投递消息队列。
账务/对账模块（Ledger & Reconcile）：订单流水、手续费、净入账、结算单、差错处理。

关键原则：业务放行以“支付成功且已确认入账”为准；所有状态以服务端查询/回调为准，避免仅依赖前端返回。

三、开通与资质准备（KYB/KYC 与风控前置）

为降低后续限额、拒付与冻结风险，建议在接入前一次性准备完整资料并明确业务边界：

企业/主体资料：公司注册信息、经营范围、受益人信息、对公账户或结算账户信息。
业务材料：网站/App、支付流程截图、退款政策、隐私政策、服务条款。
交易参数：预计交易量、客单价区间、主要客群、发货/交付方式、争议处理流程。
合规要求：明确是否涉及数字资产/高风险行业，提前规划风控策略与限额方案。

四、核心接口流程（下单、跳转/扫码、回调、查询、退款）

1）下单（Create Payment）

必须字段：merchant_order_id、amount、currency、customer_id（或等价标识）、notify_url、return_url、sign。
推荐字段：商品描述、设备信息、IP、风控标签（risk_level/scene）用于提升通过率。
幂等设计：同一 merchant_order_id 重复请求必须返回同一支付单结果，避免重复扣款。

2）拉起支付（Redirect / QR / Paylink）

H5/PC：返回跳转链接（redirect_url）或收银台链接（pay_url）。
App：建议使用 Deep Link/SDK（如适用）或安全跳转页，并兼容回到 App 的返回路径。
线下：使用二维码（qr_content）或动态码，保证过期机制与金额一致性。

3）异步回调（Webhook）

回调是支付闭环的“最终裁判”。必须做到：验签、幂等、可重试、可追踪。

验签：按币付签名规则校验签名与时间戳（如有），拒绝伪造请求。
幂等：以 transaction_id + status 或 merchant_order_id + paid_at 做唯一约束，重复回调只更新一次。
状态机：仅允许状态单向推进（created → pending → success/failed → refunded）。
落库后应答：先写入数据库/消息队列，再返回成功应答，避免丢单。

4）主动查询（Query Payment）

当回调延迟、网络波动或用户未完成返回时，务必以服务端查询结果作为补偿机制：

支付超时：定时查询更新订单状态并触发业务后续动作。
回调未达：以查询结果回填，并记录差错原因以便排查。

5）退款（Refund / Partial Refund）

校验：仅允许对成功单退款；部分退款需校验累计退款金额不超过原单金额。
账务：退款需要生成独立退款流水，关联原 transaction_id 与 refund_id。
对账：退款也应在对账单中可追溯（原单、手续费、净额变化）。

五、GCash 与 Maya 的差异化处理要点

支付唤起方式：可能存在跳转链路、二维码内容与授权流程差异，建议统一封装为“支付链接/二维码 + 状态查询”。
成功判定：以回调/查询为准，避免仅依赖前端“返回成功”提示。
失败原因：将通道错误码映射为标准化错误（余额不足、超限、用户取消、风控拒绝等），便于前端提示与运营统计。

六、费率与结算说明

[rate-table type="all"]

七、对账与清分结算（企业必须做的“第二闭环”）

对账不是可选项。建议至少具备以下能力：

交易台账：订单号、支付单号、通道流水号、状态、金额、手续费、净额。
结算单管理：按结算批次归集交易，支持导出与审计。
自动差错：订单成功但未入账、入账但本地未标记成功、重复回调等自动识别。
补单机制：针对回调丢失/延迟的订单执行自动补偿更新。

八、代付/出款能力（如业务需要）

当业务涉及佣金发放、商户结算、用户提现等场景，可通过币付提供的代付能力实现统一出款管理：

风控前置：出款前做账户校验、黑名单校验、频次/金额限额。
幂等：代付单号必须全局唯一，避免重复打款。
可追溯：记录出款请求、处理状态、失败原因与回执信息。

九、安全与稳定性

签名与密钥：密钥分环境管理，严禁写入前端或公开仓库。
IP 白名单：回调接口启用来源限制（如适用）并配合验签。
重放保护：校验时间戳/nonce（如协议提供），并设置请求有效窗口。
超时与重试：支付下单、查询、退款均需设置合理超时、退避重试与熔断。
监控告警：成功率、回调延迟、错误码分布、对账差错率必须可视化。

十、上线前检查清单

回调验签通过，重复回调幂等正确。
支付成功后业务发货/交付逻辑只由服务端触发。
订单超时补偿与主动查询已上线并验证。
退款/部分退款流程可用，账务流水完整。
对账导出与差错处理流程明确（责任人、处理时限、补偿方式）。
风控策略与限额策略生效（异常频次、异常金额、异常地区/设备）。
监控、日志、告警已配置，关键链路可追踪。

十一、常见问题与处理建议

用户已扣款但订单未成功：优先查支付单状态与通道流水，必要时走补单与人工复核流程。
回调收不到：检查回调地址可达性、HTTPS 证书、WAF/防火墙、超时设置与验签失败日志。
成功率波动：按错误码分布定位（风控拒绝/用户取消/网络问题/通道维护），再做分策略优化。
对账差错：核对订单维度字段完整性（订单号、通道流水、金额、手续费、净额、状态时间）。

联系币付（Bifu）

如需获取更适配您业务的接入方案（含接口文档、联调支持、费率与结算配置、风控策略建议），请联系币付：

Telegram：@Bifuapp
邮箱：[email protected]