币付原生 GCash 支付通道：代收代付接入流程、回调验签与对账风控要点

币付面向出海商户、跨境团队与本地运营方，提供菲律宾原生 GCash 支付通道的代收代付能力，覆盖收款、付款、订单状态回调、对账与风控闭环，帮助业务在菲律宾市场实现更稳定的支付链路与更可控的资金流程。

代收：用户使用 GCash 完成付款，平台侧实时或准实时收到订单状态回调
代付：向用户或合作方发起打款，支持订单化出款与结果回执
对账：逐笔核对 + 汇总核对，降低漏单、重单、错单
风控：黑名单、限额、频控、实名核验与异常行为识别

一、适用场景与接入边界

币付的 GCash 原生通道适用于菲律宾本地收款与出款场景，常见行业包括电商、数字服务、订阅、教育、工具类应用、内容付费、票务与本地生活等。为确保链路稳定与资金安全，建议在接入前把以下边界一次性定义清楚：

业务形态：资金流向（用户付款、平台代付、分账），交易闭环（下单 → 支付 → 发货或交付）
资金模型：是否需要余额体系、冻结/解冻、退款、撤销、冲正
合规要求：KYC/AML、可疑交易监测、交易凭证留存、争议处理流程
技术形态：API 接入或 H5/收银台跳转，移动端与 Web 端兼容策略

二、整体架构：从下单到入账的关键链路

建议将支付系统拆分为五个模块，降低耦合并提升可维护性：

订单域：生成商户订单号 merchant_order_no，定义金额、币种、商品/服务信息与超时策略
支付域：创建支付单 payment_no，生成支付参数并返回前端发起支付
回调域：接收币付回调，验签、幂等、状态机推进（只允许状态向前）
对账域：按日或按批拉取对账数据，核对订单与资金流水，输出差错单
风控域：交易前置拦截 + 交易后复核，避免高风险交易进入资金链路

三、代收接入：标准流程与状态设计

1）创建支付（商户侧）

商户系统生成订单后，向币付发起“创建支付”请求，推荐字段如下：

merchant_id：商户号
merchant_order_no：商户订单号（全局唯一）
amount：金额（按接口规范，建议统一最小货币单位或两位小数）
currency：PHP
notify_url：异步回调地址（必须公网可访问，建议 HTTPS）
return_url：同步跳转地址（可选，用于前端体验）
subject/body：订单描述（控制长度，避免特殊字符）
client_ip/device_info：风控辅助字段（可选）

2）拉起支付（前端侧）

币付返回支付参数后，前端可通过收银台/H5/跳转方式发起 GCash 支付。前端只负责展示与拉起，订单最终结果必须以异步回调为准，避免因用户中断或网络抖动造成误判。

3）异步回调（以回调为准）

币付在支付状态变化时向商户 notify_url 发送回调。商户侧回调处理建议做到四件事：

验签：校验签名与报文完整性，拒绝未通过验签的请求
幂等：同一 payment_no 或 merchant_order_no 多次回调只处理一次
状态机：只允许状态从“待支付”推进到“成功/失败/关闭”，不允许回退
快速响应：先落库再异步执行业务逻辑，回调接口尽量轻量

4）推荐订单状态枚举

PENDING：已创建支付单，待用户支付
PROCESSING：支付处理中
SUCCESS：支付成功（可发货或交付）
FAILED：支付失败（可引导重试）
CLOSED：关闭或超时（需用户重新下单）

四、回调验签与安全：把回调可信做成工程能力

支付系统最常见的事故不是“成功率低”，而是回调被伪造、重复通知导致重复记账、日志缺失导致无法追责。币付建议商户侧按以下方式做安全与可靠性建设：

全链路 HTTPS：notify_url、查询接口建议统一 HTTPS
签名一致性：请求参数按约定排序拼接，使用密钥生成签名；回调验签必须一致
时间戳与随机串：降低重放风险（按接口规范实现）
回调来源控制：在允许的情况下配置来源 IP 白名单
日志脱敏：账号、手机号、证件号等敏感信息做掩码处理

回调处理建议流程：

1) 读取回调参数与原始报文
2) 验签：verify_signature(payload, secret)
3) 幂等：以 payment_no 或 merchant_order_no 做唯一键
4) 状态推进：只允许 PENDING → SUCCESS/FAILED/CLOSED
5) 落库：写入支付流水、回调日志、验签结果
6) 返回成功响应：避免对方重复重试

五、代付接入：出款订单化与风控控制

代付用于向用户或合作方出款，例如佣金结算、提现、商户分润等。强烈建议把代付设计成“出款订单”，与业务单据强绑定，确保可追溯、可对账、可审计。

1）代付发起前的必做校验

收款人信息校验：账号格式、姓名一致性（如有）、必要字段完整性
限额与频控：单笔、单日、单用户、单设备、单 IP 维度限额
风险画像：新用户高频提现、异常设备、异常位置、黑名单命中
资金可用性：余额、冻结资金、在途资金的核算口径必须统一

2）代付结果回执与补偿机制

代付通常存在处理中/成功/失败等状态。商户侧需要准备补偿与兜底，避免“出款已发生但系统未记录”或“系统重试导致重复出款”。

查询兜底：回调丢失或超时，按 payout_no 主动查询最终状态
失败重试：只对可重试错误重试；不可重试错误直接失败并提示
重复出款防护：幂等键 + 出款订单唯一约束 + 状态锁

六、对账与差错处理：让财务与技术都能闭环

代收代付系统的稳定不仅是支付成功率，更是账务一致性。建议建立两层对账机制：

订单对账：逐笔核对订单金额、状态、渠道流水号、手续费口径
汇总对账：按日或按批核对总入账、总出账、退款与净额

差错处理建议按类型分流：

我方有单、渠道无单：标记为疑似未支付，触发查询与人工复核
渠道有单、我方无单：高优先级补单或回填，避免漏发货或漏入账
金额不一致：核查币种、精度、折扣、手续费口径与订单改价记录
状态不一致：以渠道最终状态为准，同时保留证据链与处理记录

七、稳定性与可观测性：把偶发问题变成可定位问题

当用户反馈不到账时，系统必须能快速回答“卡在哪一步”。建议内置以下可观测能力：

核心指标：创建成功率、支付成功率、回调到达率、平均确认时延、代付成功率
关键日志：请求入参、响应码、验签结果、状态流转、重试次数、异常栈
告警策略：成功率突降、回调堆积、查询超时、差错单激增、余额异常波动
链路追踪：订单号贯穿前后端与服务，统一 Trace ID 便于定位

八、费率与支持通道

币付支持菲律宾本地高频收款方式与扫码场景，包含 GCash 与 QRPH 等能力。具体费率与结算安排以实际开通的商户配置为准。

[rate-table type="all"]

九、商户接入准备清单

基础资料：公司主体信息、业务说明、网站或应用信息、客服与争议处理流程
技术准备：公网 HTTPS 回调地址、服务器可用性保障、签名与验签实现
账务准备：对账人员、对账周期、退款与冲正规则、结算口径确认
风控准备：黑名单策略、限额策略、异常交易处理 SOP 与留证规范

十、常见问题

1）为什么强调以异步回调为准？

同步跳转依赖用户行为与网络状态，不具备可靠性；系统对系统的回调才是支付确认的可信来源。

2）回调重复通知怎么办？

必须做幂等：数据库唯一键 + 状态机推进规则 + 业务侧只处理一次的锁机制。

3）回调没来但用户显示已扣款怎么处理？

走查询兜底：先按订单号查询渠道最终状态，再决定补单、发货或退款，并保留查询与处理记录作为证据链。

联系币付获取接入资料

如需获取 GCash 原生通道接入参数、联调文档、回调验签示例与上线检查清单，请联系币付客服：

Telegram：@Bifuapp
邮箱：[email protected]

提交对接需求时，建议同时提供：业务类型、预估交易量级、代收/代付需求、系统形态（Web/App）、以及对账与结算偏好，便于快速评估并安排联调。