菲律宾三方支付接入 GCash 指南：账单查询、对账与代收代付问题说明

本文面向需要在菲律宾市场接入 GCash 能力的商户与技术团队，聚焦三方支付接入的关键环节：下单与收款、账单查询与对账、代收与代付的常见问题与处理口径。内容以工程落地为导向，帮助你快速形成可执行的对接规范与客服处理流程。

一、业务范围与基本概念

1. 角色划分

商户系统：发起收款、查询订单、接收支付结果通知；如能力支持，可发起退款或撤销。
币付 Bifu：提供统一接入、交易编排与风控能力，对接上游通道并向商户输出支付能力与交易结果。
GCash 与上游通道：承载用户侧支付工具与通道规则，返回支付结果与必要的追踪信息。

2. 核心交易类型

收款：用户完成支付，交易进入结算路径，商户以订单为单位确认最终结果。
付款：商户向个人或企业打款，商户以打款单为单位确认结果与失败原因。
账单与对账：核验订单与打款单的状态、金额、手续费与净额，完成财务闭环。

二、接入流程要点（工程落地视角）

1. 接入前准备清单

商户信息：主体信息、业务场景、收款用途、退款与售后规则、客服联系方式。
技术信息：回调域名与证书、IP 白名单策略（如采用）、签名密钥管理方式、日志留存与审计要求。
交易要素：币种、金额精度、订单号规则、幂等策略、超时与重试策略、异常兜底方案。

2. 标准交易链路（以可观测为核心）

创建订单：商户向币付提交订单信息，获取支付参数、跳转链接或二维码等支付载体。
用户支付：用户在 GCash 完成授权与支付。
结果确认：以回调通知为主、主动查询为辅，双通道闭环确认订单最终态。
账单与对账：按订单维度与账单维度核验一致性，定位差异并完成处理闭环。

3. 必须落地的三项能力

幂等：同一订单的创建、确认、退款请求必须可幂等，避免重复扣款或重复入账。
状态机：明确状态流转，例如待支付、处理中、成功、失败、关闭、退款成功，并定义每个状态允许的动作。
可观测性：至少具备请求 ID、商户订单号、币付交易号、上游流水号、回调原文、验签结果、重试次数、最终态落库时间等字段。

三、账单查询与对账：不要把两类查询混用

1. 两类查询的定位

订单查询：面向单笔交易，回答订单是否成功、成功金额是多少、对应通道流水是什么。用于客服追单、补单与异常兜底。
账单与结算查询：面向一段交易集合，回答应收、实收、净额、差异等统计口径。用于财务对账与结算核验。

2. 订单查询建议使用的关键字段

商户订单号：商户侧唯一标识，建议具备可追溯性，例如业务线前缀加随机数或雪花 ID。
币付交易号：币付侧唯一标识，用于跨系统定位与排查。
上游流水号：如通道返回，上游流水号是争议与追踪的重要依据。

3. 对账必备口径

金额口径：订单金额、用户实付金额、应结算金额、手续费与净额必须定义清晰，并统一精度规则。
状态口径：成功、失败、处理中、关闭、退款成功等状态必须与商户内部状态一一映射。
差异定位顺序：优先按订单查询结果，再看回调日志，再看上游流水，最后看账单汇总。

四、代收常见问题与处理口径

1. 回调未到或回调延迟

现象：用户提示已支付，但商户未收到成功通知，订单停留在待支付或处理中。

以主动查询作为兜底，按订单号查询最终态并落库。
检查回调地址可达性、TLS 证书、商户返回码策略，以及验签失败是否被直接丢弃。
回调处理必须可重入：同一通知多次到达必须可重复消费且不产生副作用。

2. 用户被扣款但订单失败或关闭

现象：商户侧显示失败或超时关闭，但用户侧资金已扣。

可能是支付成功但回调丢失或商户处理失败。
可能是支付处理中，商户过早关闭导致状态不一致。
可能是上游最终失败并触发原路退回，但用户侧展示存在延迟。

处理口径：以最终交易状态为准落库。如需退款或冲正，必须走平台支持的标准能力，并记录原因码与处理轨迹。

3. 重复扣款或重复订单

高风险触发：用户重复点击、商户重复下单、网络重试导致重复创建订单。

下单接口必须幂等：同一业务单只允许映射一个有效支付订单。
订单处于处理中时禁止再次发起新支付，改为引导查询并等待最终态。
必要时启用业务锁或支付会话机制，避免并发创建。

五、代付常见问题与处理口径

1. 代付失败原因归类

收款方信息不匹配：姓名、账号、手机号等要素不一致导致失败。
风控拦截：异常频率、异常金额、异常设备或 IP、黑名单等触发策略。
账户状态异常：收款账户受限、不可用或未完成必要验证。
系统性失败：网络超时、上游接口异常、重试超过阈值。

2. 代付状态管理原则

建议状态：已受理、处理中、成功、失败、需人工复核（如支持）。
任何处理中都不能当作成功入账，必须等待最终态或通过查询确认后再变更余额或订单。
失败必须记录原因码与可读描述，并区分可重试与不可重试，避免盲目重试引发更高风控。

六、对账与争议处理：把流程固化为最小闭环

1. 对账最小闭环

以币付账单或交易汇总为基准，核验商户系统成功订单集合。
对差异订单逐笔回溯：订单查询结果、回调日志、商户入账记录、退款记录。
输出差异结论：缺回调、重复入账、金额不一致、退款未同步、订单号映射错误等。
形成自动修复策略：补发通知、补单入账、冲正重复、同步退款状态。

2. 争议处理建议材料

商户订单号、币付交易号、上游流水号。
用户支付凭证截图（如用户提供）、支付时间点范围。
商户系统日志：请求与响应、回调原文、验签结果、落库记录（需脱敏）。
期望处理结果：确认成功、发起退款、撤销、补发回调等。

七、安全与合规要点

回调验签：所有回调必须验签，验签失败必须拒收并记录原文。
密钥管理：密钥不落日志、不写前端；支持轮换并保留双密钥兼容窗口。
敏感信息最小化：只采集完成交易所需信息，存储与传输需脱敏与访问控制。
风控配合：高风险交易建议支持人工复核、黑白名单、限额与频控策略。

八、常见问答

Q1：用户说已付款，系统还显示未支付怎么办？

A：先做订单查询确认最终态。若查询为成功，以成功落库并补发通知；若为处理中，保持处理中并持续查询；若为失败，按失败原因解释并引导用户确认资金状态。

Q2：账单里有成功订单，但我系统没有记录？

A：先排查回调可达性与验签逻辑是否丢弃，再排查订单号映射与幂等逻辑，最后按交易号补单入库并补齐对账数据。

Q3：代付失败能不能一直重试？

A：不能。信息不匹配与账户状态异常通常不可盲目重试；系统性失败可在控制频率与次数前提下重试，并保留每次请求与响应记录。

Q4：出现重复扣款怎么处理？

A：先确认是否为重复订单或同单重复支付，使用币付交易号与上游流水核对；必要时按平台能力发起退款或冲正，同时修复幂等与并发治理，避免再次发生。

九、费率与结算

币付支持 GCash 与 QRPH 等菲律宾本地支付方式的代收与代付能力，费率以实际开通与风控评估结果为准。以下为费率展示组件：

[rate-table type="all"]

十、接入支持与问题反馈

如需获取币付对接资料、回调验签规范、对账字段口径说明，或协助定位交易问题，请通过以下方式联系：

Telegram：@Bifuapp
邮箱：[email protected]

为提升排查效率，建议提交时一并提供：商户订单号、币付交易号、问题现象描述、相关日志片段（脱敏后）、以及期望处理结果。