币付支付平台：菲律宾原生 GCash / QRPH 支付接入与代收代付对接文档

币付（Bifu）为商户与平台型业务提供菲律宾本地化支付能力，支持原生 GCash 收款、QRPH 扫码、代收、代付与对账结算等关键链路，面向电商、数字内容、订阅服务、线下扫码收款、跨境业务等场景，提升支付稳定性与资金流转可控性。

本文聚焦对接要点、能力边界、安全与风控实践、上线交付标准，帮助技术与业务团队快速评估并完成集成。

一、能力范围与适用对象

1）适用对象

电商平台 / 独立站：本地用户使用 GCash 或 QRPH 完成支付闭环
数字化服务：会员订阅、虚拟权益、在线教育、游戏充值等
线下 / 线上融合：收银台、二维码收款、订单系统统一管理
平台型业务：多商户入驻、资金归集、清分/分账、统一对账与风控

2）核心能力

原生收款：GCash 收款链路、QRPH 扫码链路（下单、支付、回调、查询、对账）
代收代付：资金归集、批量代付、失败重试、异常处理与可追溯流水
订单与账务：交易状态机、对账单、余额/流水查询；退款/冲正能力按开通范围提供
风控与合规：商户准入、交易风控、黑名单/限额/频控策略按业务模型配置

二、对接架构（商户侧视角）

标准对接由三部分组成：下单接口、异步通知（Webhook）、查询与对账接口。建议商户采用“异步通知为准、主动查询兜底”的设计，避免网络抖动导致订单不一致。

交易状态建议（运营与研发统一口径）

CREATED：订单已创建，待支付 —— 展示支付引导；设置超时取消策略
PROCESSING：支付处理中 / 等待渠道确认 —— 等待页；后台定时查询；避免重复发货
SUCCESS：支付成功 —— 发货/发放权益；记录入账凭证；进入对账流程
FAILED：支付失败 —— 提示重试或更换方式；保留失败原因用于风控与转化分析
CLOSED：订单关闭 / 超时取消 —— 释放库存；关闭支付入口

三、接入流程（落地交付标准）

商户准入：提交业务资料、结算信息、交易场景说明；完成合规评估与风控策略确认。
开通与配置：分配商户号/应用号、API 密钥；配置回调地址；按需配置 IP 白名单等安全策略。
联调测试：覆盖下单、支付、回调验签、查询、对账；必须覆盖成功/失败/超时/重复通知等用例。
灰度上线：小流量验证订单一致性与资金对账；重点观察成功率、回调延迟、差错率与告警。
正式运行：启用风控策略与自动化对账；建立异常工单与应急预案，确保可审计与可追溯。

四、关键技术点（接口、验签、回调）

1）接口调用建议

全链路使用 HTTPS；请求与响应统一 UTF-8 编码；字段命名与类型严格校验。
请求建议携带商户标识、签名、随机串/时间戳等防重放字段（以实际对接字段为准）。
业务幂等：商户侧以 merchant_order_no（或等价字段）作为幂等键；重复下单应返回同一笔交易结果，而不是生成新单。

2）Webhook 异步通知（必须实现）

必须支持重复通知：同一交易可能被多次通知，商户必须幂等处理，否则会出现重复入账/重复发货。
验签失败必须拒收：验签失败直接拒收并记录日志；不要“先成功后补验”，这是风险点。
建议回包规范：返回 HTTP 200 + 固定成功标识作为确认；其余均视为未成功，系统将按策略重试。

3）签名机制（说明）

签名通常采用“按字段排序 + 拼接 + 密钥摘要”的方式。商户需确保：

参与签名字段不多签、不漏签
金额、币种、订单号等关键字段不可被篡改
签名校验失败需输出可追踪错误码，并保留脱敏后的原始请求日志

验签流程示例（以实际对接文档字段清单为准）：
1) 取出通知中的 sign 字段
2) 将除 sign 外的字段按字典序排序
3) 按 key=value 拼接，末尾拼接密钥
4) 计算摘要，与 sign 比对

五、资金与对账（建议的运营方式）

1）结算与账务

支持按协议约定的结算周期与打款方式（例如 T+0/D0 等）；可配置结算阈值、自动结算与人工审核策略。
建议建立“三表体系”：订单表 + 资金流水表 + 对账差异表，确保财务可审计、可追溯、可重跑。

2）对账建议

以币付对账单为基准逐笔核对：订单号、渠道流水、金额、手续费、状态。
差异单自动归类：重复回调、用户中断、渠道延迟、退款/冲正、人工补单。
对账链路必须可重跑：同一账期重复拉取与核对不得产生二次入账。

六、安全、风控与合规（必须落实）

数据安全：敏感字段脱敏存储；密钥分级管理；日志不得明文记录密钥与完整敏感信息。
访问控制：接口鉴权、IP 白名单、回调来源校验；关键操作增加审批或二次校验。
交易风控：限额、频控、黑名单、设备/行为特征策略按业务复杂度启用。
合规运营：商户准入与交易场景需真实可核验；高风险品类需提前披露并按要求审核。

七、费率说明（实时以后台配置为准）

下方为币付已配置的费率表模块，包含 GCash 与 QRPH 的实施费率展示：

[rate-table type="all"]

八、常见问题（FAQ）

Q1：为什么支付成功但商户未发货？

最常见原因是回调未正确验签、回调处理超时、或回调地址偶发不可用。务必以 Webhook 为主、查询为兜底，并对回调接口做性能与重试设计。

Q2：如何避免重复入账 / 重复发货？

以商户订单号或交易号做幂等键，入账/发货前先查状态；同一交易多次通知只允许一次成功动作。

Q3：接入周期如何把控？

关键在于联调用例完备与异常场景覆盖。至少覆盖：成功、失败、超时、重复通知、网络中断、查询兜底、对账差异处理。

九、联系币付获取对接资料

如需获取完整接口字段定义、签名规则、回调示例、测试环境参数与商户准入清单，请联系币付：

Telegram：@Bifuapp
Email：[email protected]