菲律宾 GCash 支付接口接入指南：下单流程、回调验签、幂等处理与安全风控闭环｜币付 Bifu

面向在菲律宾开展业务的商户，如果你希望快速接入 GCash 并提升本地用户支付转化，本文给出一套可落地的接口对接方案：从开通准备、服务端下单、调起支付，到异步回调验签、幂等处理、主动查询兜底、退款状态机与风控加固，帮助你少踩坑、快上线、跑得稳。

一、为什么要接入 GCash 支付

GCash 是菲律宾覆盖面极高的本地电子钱包之一。对商户而言，接入后通常能带来：

• 更顺滑的本地支付体验：减少跳出，提高支付成功率与复购。
• 更轻的收款门槛：适配 H5、App WebView、扫码等常见场景。
• 更清晰的对账与风控闭环：订单号 + 通道流水 + 回调状态 + 主动查询，降低差错与争议。

二、适用场景

• 电商与独立站：下单支付、预付、尾款等
• 数字内容与订阅：会员订阅、点播、下载、工具类服务
• 游戏与虚拟充值：高并发高频小额（点券、礼包、道具）
• 线下与社群收款：二维码收款、活动报名、桌面端收银

三、常见接入方式（聚合网关 vs 原生直连）

• 聚合网关接入（推荐）：通过币付（Bifu）统一 API 覆盖多通道（含 GCash、QRPH 等），统一回调、统一对账与结算口径，更利于扩展与稳定跑量。
• 原生通道直连：更贴近通道规则，但接入与维护成本更高（签名规则、字段口径、回调重试、对账差异等需要逐个处理）。

四、实时费率（GCash + QRPH）

下方为币付提供的 GCash 与 QRPH 实时费率展示（以后台实时配置为准）：

五、接入前准备清单

• 商户资料：主体信息、业务介绍、网站或 App 信息、必要的风控说明。
• 结算与退款路径：结算账户、退款资金来源、异常争议处理方式与 SLA。
• 接口配置：notify_url（异步回调）、return_url（前端返回）、服务器公网 IP（用于白名单）。
• 密钥管理：API Key / Secret 存储方式、权限隔离、轮换策略、最小权限原则。

建议在研发启动前统一好：支付成功口径、退款口径、异常处理口径，避免上线后反复改逻辑。

六、标准对接流程（下单 → 调起 → 回调 → 查询兜底 → 对账）

步骤 1：服务端创建订单（下单）

由商户服务端发起创建订单请求，拿到用于调起支付的 pay_url 或二维码数据 qr_data。关键字段建议“稳定、可对账、可追溯”。

• order_no：商户侧唯一订单号（推荐雪花/时间戳+随机数），不可重复
• amount：金额（统一小数位或最小货币单位，避免浮点误差）
• currency：币种（如 PHP）
• subject：商品/服务描述（用户识别、客服与对账更顺畅）
• notify_url：异步回调地址（公网可达，建议 HTTPS）
• return_url：前端返回地址（用户支付后跳回）
• client_ip：用户 IP（按风控需要使用）
• metadata：透传字段（如 user_id、channel_id、scene 等，便于定位）

步骤 2：请求签名与回调验签（安全核心）

签名与验签是最核心的安全点。常见做法为 HMAC-SHA256 / MD5 等（以实际通道或币付对接文档为准）。建议遵循：

• 签名前先按规则对参数进行排序，空值字段按约定处理
• 金额与币种必须纳入签名，金额格式必须统一
• 验签对比建议使用常量时间比较，降低时序攻击风险

签名示例（思路）
1) 参数按规则排序（字典序）
2) 拼接 canonical_string：key=value&key=value...
3) 使用 secret 对 canonical_string 做 HMAC-SHA256 得到 sign
4) 回调验签时按同样规则重算 sign 并对比（建议常量时间比较）

步骤 3：调起支付（H5 / App / 扫码）

• 移动端：使用 pay_url 跳转收银台或唤起支付页（H5 / App WebView 常见）
• PC 与线下：展示 qr_data，或把 pay_url 生成二维码收款（可结合 QRPH 扫码场景）

注意：前端只负责展示与跳转；订单创建与签名必须在服务端完成，避免密钥泄露。

步骤 4：异步回调处理要点（验签 + 幂等 + 落库）

回调是入账依据之一。建议按固定顺序处理，形成稳定闭环：

1. 先验签：签名不通过直接拒绝处理
2. 核对关键字段：订单号、金额、币种、商户号必须与本地订单一致
3. 幂等处理：同一订单可能多次回调，必须“重复通知不重复入账、不重复发货”
4. 落库再发货：先写入支付状态与通道流水号，再触发发货/开通权益
5. 返回成功应答：按约定返回固定成功字符串（例如 success / OK），否则通道会重试

建议建立唯一约束：order_no 唯一 + 支付成功只能写一次，并记录通道流水号以便对账。

步骤 5：主动查询兜底（掉单与补单关键）

即使回调链路完善，也要保留“主动查询订单状态”的能力，用于：

• 用户网络中断导致支付页未返回
• 回调链路短暂不可用
• 定时巡检未完成订单，自动纠偏与补单

步骤 6：对账与结算口径

建议以“商户订单号 + 通道流水号 + 支付时间 + 手续费 + 净额”为主线建立对账口径，并在币付侧统一导出对账/结算报表，减少人工核对成本与争议。

七、退款流程（建议状态机）

退款建议使用独立的 refund_no 与退款金额，采用状态机管理，避免“请求一次就当最终结果”。

• 退款请求同样需要签名与验签，并确保幂等
• 退款状态建议：申请中 / 成功 / 失败，并与订单状态关联
• 保留退款原因字段，便于客服与风控分析

八、安全与风控加固建议

• HTTPS 全链路：notify_url 建议使用 HTTPS，并监控证书有效期与链路稳定性
• 回调来源控制：结合 IP 白名单与 WAF，只允许通道来源访问回调接口
• 防重放：引入 nonce / timestamp / 有效期字段，并在服务端做去重校验
• 幂等兜底：以 order_no 做唯一键，支付成功只允许落一次
• 日志与审计：保留请求/回调/验签结果/流水号关键快照（注意脱敏）
• 分层风控：频控、黑名单、异常金额拦截、设备/账号维度限制，按风险级别分层

九、常见问题排查

• 收不到回调：检查回调地址公网可达、DNS、SSL、WAF/防火墙策略，以及是否按约定返回成功字符串
• 回调验签失败：检查参数排序、编码规则、空值处理、密钥一致性、金额格式一致性
• 用户显示已支付但商户未入账：先用主动查询确认通道侧状态，再核对本地幂等与落库逻辑
• 重复发货/重复开通权益：幂等未做好，必须用订单状态机 + 唯一约束兜底

十、快速上线清单

• 确定接入方式与支付形态：聚合网关 / 原生直连；跳转 / 二维码（含 QRPH 场景）
• 申请并配置关键项：商户号、密钥、notify_url、IP 白名单
• 完成闭环：下单、调起、回调验签与幂等、主动查询兜底、对账与结算口径
• 上线前压测：高并发下单、回调重试、网络抖动、重复通知
• 上线后监控：支付成功率、回调成功率、异常订单数、对账差异

需要对接支持

如果你希望用更省开发成本的方式接入菲律宾本地支付（含 GCash），并把回调验签、对账与风控一起做成稳定闭环，同时支持 QRPH 等更多通道扩展，可以联系币付获取接入资料与技术支持。

• Telegram：@Bifuapp
• 邮箱：[email protected]