菲律宾本地支付通道接入指南：GCash收款流程、回调验签与对账结算要点（币付）

GCash 作为菲律宾覆盖率极高的本地电子钱包之一，已成为电商、线上娱乐、数字内容、O2O 服务等业务的关键收款方式。本文面向商户技术与运营团队，系统梳理 GCash 支付通道的接入流程、接口设计要点、回调验签、风控与对账结算方法，帮助你以更低的集成成本获得更稳定的支付成功率与资金可控性。

一、接入前必须明确的业务边界

收款场景：H5/网页收银台、App 内嵌页、二维码收款、跳转授权收款等。
交易链路归属：订单创建、收银引导、支付确认、异步回调、主动查询、退款/撤销、对账结算。
资金路径：入账主体、清算方式、结算周期（如 T+0/T+1）、原路退回策略、异常处理规则。
合规与风控要求：结合业务类型明确 KYC/AML、交易监控、黑名单、可疑交易处置等要求，并与合规/法务对齐。

二、推荐的系统架构与接口原则

支付服务独立化：将“支付创建 / 查询 / 回调 / 对账”封装为独立服务或模块，降低业务系统耦合。
全链路幂等：订单号（merchant_order_id）与支付单号（payment_id）双重幂等；回调重复触发必须可重入。
状态机驱动：只允许从合法状态迁移，例如 CREATED → PENDING → SUCCESS / FAILED → REFUNDED。
安全默认：签名验真、时间戳防重放、必要时使用 IP 白名单；敏感信息最小化存储与传递。

三、商户侧准备清单（上线前一次性做对）

商户资料与结算信息：公司/个人主体信息、结算账户、对账联系人、风控联系人。
必要技术参数：
- notify_url：用于接收异步支付结果
- return_url：用于前端展示支付结果
- API Key / Secret：用于鉴权与签名
订单字段规范：
- merchant_order_id：你方唯一订单号，建议全局唯一
- amount / currency：金额与币种，菲律宾场景通常为 PHP
- subject / description：商品或服务描述，便于用户识别与风控判断
- client_ip / user_agent：可选字段，建议传递以增强风控与排查能力

四、GCash 收款标准对接流程（建议按此实现）

1）创建支付订单（服务端）

服务端发起“创建支付”请求，拿到支付单号与收银参数（或跳转链接）。

POST /pay/create
{
  "merchant_order_id": "2026xxxxxxx",
  "amount": 1999,
  "currency": "PHP",
  "channel": "GCASH",
  "notify_url": "https://merchant.com/pay/notify",
  "return_url": "https://merchant.com/pay/result",
  "description": "Premium Membership"
}

2）引导用户完成支付（前端/收银台）

跳转授权：跳转到 GCash 或收银页，由用户确认支付。
二维码：展示二维码，用户扫码完成支付，适用于线下或半线下场景。

3）接收异步回调（服务端，关键）

支付成功与否以异步回调为准。回调处理必须做到：验签、幂等、落库、响应快速。

验签：按约定签名算法校验 sign 与 timestamp，防篡改与重放。常见做法是 HMAC-SHA256。
幂等：同一 payment_id 或 merchant_order_id 的 SUCCESS 回调可能重复推送，必须可重复执行但只生效一次。
快速响应：完成验签与入库后立即返回 success，再异步触发发货/开通权益等业务动作，避免回调超时导致重复推送。

// 回调处理要点示例（结构化表达）
if (!verify_signature(payload, secret)) return 400;
if (is_replay(payload.timestamp, payload.nonce)) return 400;

order = find_order(payload.merchant_order_id);
if (!order) return 404;

if (order.status == "SUCCESS") return 200; // 幂等：重复回调不重复发货

update_order_status(order, payload.status, payload.payment_id);
enqueue_business_fulfillment(order);

return 200;

4）主动查询兜底（服务端）

当用户端显示“处理中”、回调延迟或网络异常时，必须提供“主动查询”能力兜底，避免误判与投诉升级。

前端轮询，或用户点击“我已支付”触发查询
定时任务扫描 PENDING 超时订单并触发查询

五、退款 / 撤销与代付（按业务需要选择实现）

退款：建议同时支持全额退款与部分退款；记录 refund_id 并保持幂等。
撤销：通常仅适用于未完成清算或特定状态，按通道规则执行。
代付/出款：若涉及代付，务必配置更严格的风控与审核流程，包括限额、名单、二次确认、资金预警与审批链路。

六、费率与结算说明

以下为币付已配置好的费率表展示代码，包含 GCash 与 QRPH：

[rate-table type="all"]

结算周期：常见为 T+0 / T+1，具体以签约配置为准。
对账单：建议每日生成对账文件，包含订单维度、通道流水号、手续费、净额、状态等字段。
差错处理：建议工单化闭环，覆盖长款、短款、重复扣款、用户投诉等场景，做到可追踪、可回放、可复盘。

七、风控与稳定性：决定你能跑多大规模

1）常见风控策略（商户侧可落地）

设备与账号维度：同设备多账号、同账号多设备、异常登录频次。
交易行为：短时间高频小额、集中失败重试、金额跳变。
名单体系：黑名单/灰名单/白名单与动态调整机制。
限额控制：单笔/单日/单用户/单设备限额。

2）稳定性工程（必须做）

超时与重试：创建支付、查询、退款等接口设置合理超时；重试需有退避策略，避免雪崩。
熔断降级：通道异常时切换备用通道或提示稍后重试，避免拖垮业务系统。
可观测性：支付成功率、回调延迟、失败码分布、订单停留时长等指标要可视化，并具备告警。

八、上线验收清单（逐项验收）

创建支付：金额、币种、订单号规则正确；收银页正常展示。
回调验签：篡改参数必须被拒绝；重复回调不重复发货。
主动查询：处理中/异常网络情况下可正确回补状态。
退款链路：成功/失败/重复请求幂等验证通过。
对账：通道流水与商户订单可一一匹配，差错可追踪可定位。
监控告警：成功率异常、回调堆积、接口超时具备告警能力。

九、常见问题与排查方向

用户已扣款但订单未成功：优先查回调日志与查询接口结果；必要时以通道流水为准回补状态。
回调收不到：检查公网可达、HTTPS 证书链、WAF/防火墙拦截、回调响应是否超时。
签名验不过：核对参与签名的字段集合、排序规则、字符编码、空值字段处理方式是否一致。
成功率波动：按失败码分布定位原因，如余额不足、用户取消、风控拒绝、通道超时，并分别优化链路与提示策略。

十、币付通道接入支持

币付（Bifu）面向菲律宾本地场景提供支付通道对接能力，支持以标准化接口快速集成，并可根据业务类型提供更贴近实战的风控与对账建议。

Telegram：@Bifuapp
邮箱：[email protected]