第三方支付平台API接口使用指南：专注菲律宾市场

面向菲律宾市场做电商、游戏、线上娱乐、订阅、数字服务或线下门店收款时，“接得快、收得稳、对得上账、提得出款”比什么都重要。本指南以币付 Bifu Pay为例，系统讲清第三方支付平台 API 的接入逻辑、关键参数、回调验签、对账与风控要点，帮助你用最短路径完成上线并保持长期稳定。

你将获得什么能力

本地化收款：覆盖菲律宾主流支付方式，支持线上与线下多场景收款与支付结果回传，重点包含 GCash 与 QRPH 等高频场景。
标准化 API：下单、查单、退款、代付、对账等核心能力统一封装，便于快速集成与扩展。
资金与订单可追溯：支付状态、回调通知、账务流水、结算结果可闭环核对，减少“钱到了但单没变”的事故。
风控与合规基础：按业务类型提供必要的商户资料与交易监控建议，降低无效交易与争议成本。

适用对象

需要接入菲律宾本地支付的网站与 App 开发者、产品负责人
希望提升支付成功率、降低掉单率的电商与线上娱乐运营团队
有代付与批量打款需求的平台，例如分润、工资、佣金、提现
需要聚合支付与统一对账的企业，例如多通道统一对接、多业务线并行

接入前准备：务必一次做对

开通商户账号与权限
获取 merchant_id、app_id、api_key 或 secret、签名方式、API 网关地址，区分测试与生产环境。
配置回调地址
用于接收支付结果通知。建议独立接口、可水平扩展、具备幂等处理能力，并做好日志与告警。
服务器安全与网络要求
全站 HTTPS；密钥只存服务端；必要时启用 IP 白名单；日志脱敏；关键接口限流与重放防护。
订单号与金额规范
订单号全局唯一；金额使用最小货币单位并统一小数位规则；币种一般为 PHP，以实际配置为准。
业务资料与风控字段
建议准备商品或服务描述、用户标识、设备信息、IP、交付信息等，用于风控与争议举证。

两种常见接入模式：按业务选型

模式 A：API 下单加跳转或二维码收款

服务端调用创建支付订单接口
前端展示支付页或二维码
支付完成后：平台回调你的回调地址，同时你可主动查单二次确认

模式 B：收银台聚合，多通道统一入口

你只对接一个聚合收银台或统一接口
平台按成功率、限额与风控策略选择最优通道
适合多支付方式、多业务线、需要快速扩展的团队

核心流程：从下单到入账的完整闭环

Step 1：创建支付订单

由你的服务端发起请求，生成平台侧支付单号，并返回支付链接或二维码数据。

推荐请求字段示例

{
  "merchant_id": "你的商户号",
  "app_id": "你的应用ID",
  "order_no": "你方订单号，必须全局唯一",
  "amount": 1000,
  "currency": "PHP",
  "subject": "订单标题或商品名",
  "description": "订单描述，可选项",
  "notify_url": "支付结果回调地址，必须",
  "return_url": "前端同步跳转地址，可选项",
  "client_ip": "用户IP，建议填写",
  "request_id": "幂等ID，强烈建议",
  "sign": "签名字符串"
}

幂等必做：同一 request_id 重复请求必须返回同一结果，防止网络抖动导致重复下单。
金额单位统一：建议用最小货币单位传输，避免浮点误差。
order_no 永不复用：退款与重试也不要复用旧订单号，可通过扩展字段关联原单。

Step 2：展示支付

H5 与 PC：跳转支付链接或收银台页面
App：内嵌 WebView 或打开系统浏览器
线下与面对面：展示二维码，建议设置合理过期时间并支持刷新

Step 3：接收回调通知

支付平台会向你的 notify_url 推送支付结果。你必须做到验签、幂等、可重试。

验签：校验签名、时间戳与数据完整性
幂等：同一平台单号或你方订单号只允许成功入库一次
状态机：只允许从 PENDING 变更到 SUCCESS、FAILED、EXPIRED 等合法迁移
返回规范：按平台要求返回成功确认，否则平台会重试推送
先落库再确认：先写入订单与流水，再返回确认，避免丢单

强烈建议：回调成功后仍进行一次查单二次确认，尤其适用于高风险业务、异常网络环境或大额交易。

Step 4：主动查单

用于对账、补单与异常处理，典型场景如下：

用户支付完成但你的系统未收到回调
回调验签失败需要二次核对
支付超时、用户关闭页面导致状态不确定

Step 5：退款

退款能力通常与支付方式、商户资质、业务风控等级有关。建议你在系统层实现：

退款申请：支持全额或部分退款，以平台能力为准
退款状态跟踪：PENDING、SUCCESS、FAILED
退款通知：支持回调或轮询查单

Step 6：代付与提现

如果你有用户提现、分润、工资佣金发放等需求，建议使用代付接口并做好风控：

代付前校验：账户信息一致性、黑名单、频次、金额阈值、设备与 IP 风险
代付幂等：同一提现单号只允许处理一次
失败重试策略：区分可重试失败与不可重试失败，避免重复出款

签名与安全：别把系统稳定性交给运气

签名算法：优先使用 HMAC-SHA256 或平台指定算法，参数按字典序拼接后签名。
签名字段覆盖：金额、币种、订单号、时间戳、回调地址等关键字段必须参与签名。
时间戳防重放：请求与回调携带时间戳，设置可接受时间窗口。
密钥管理：密钥仅服务端保存；测试与生产环境隔离；定期轮换。
回调来源校验：以验签为主，必要时叠加来源 IP 校验，以平台提供范围为准。

对账与结算：财务最关心的三件事

订单对账
建议每日拉取交易明细或账单文件，与本地订单库按平台单号、你方订单号、金额、状态核对差异，并将差异清单自动工单化。
手续费与净入账
系统内同时记录订单金额、手续费、净额、结算批次号，便于复核与统计分析。
结算周期
不同行业与资质会对应不同的结算与风控策略。建议对接前明确结算方式、到账规则、提现与代付限额与风控要求，并在系统中做可配置化。

如何用竞争对手品牌词做选型对比

很多商户会同时评估多家服务商与通道，例如 UUpay、Safepay、Tarspay、PayerMax、Xendit、PayMongo、2C2P、Dragonpay 等。建议你不要只看宣传点，而是用下面这些维度做横向对比，才能避免上线后反复踩坑。

支付方式覆盖：是否覆盖 GCash、QRPH、Maya、GrabPay 等核心入口，线上线下是否都能跑通。
成功率与稳定性：是否支持多通道冗余、失败切换、异常兜底查单机制。
回调与幂等：Webhook 是否规范、是否支持重试、签名规则是否清晰可落地。
对账可用性：是否提供账单明细、结算批次、手续费拆分字段，差异处理是否可闭环。
结算与资金效率：结算方式是否清晰，是否支持更快的到账节奏与可配置风控策略。
风控与争议处理：是否提供风控字段建议、冻结与申诉流程是否明确。

币付 Bifu Pay 的定位是以菲律宾市场为核心，提供更容易落地的 API 接入、回调闭环与对账能力，帮助商户把支付这条链路做稳。

费率与开通方式

你可以在页面中直接展示币付已配置的实时费率表，包含 GCash 与 QRPH 的实时实施费率，方便用户快速决策：

[rate-table type="all"]

常见问题

为什么用户已扣款，但我这边订单没成功

回调被拦截或超时：检查服务器日志、WAF、网关超时与返回格式。
未做幂等：重复通知导致状态异常或被你方系统拒绝。
只依赖前端返回：同步跳转不等于支付成功，必须以回调或查单为准。

如何降低掉单率与支付失败率

支付页加载速度：CDN、压缩、减少阻塞脚本。
订单有效期策略：过期可刷新二维码或重新拉起支付，避免用户停留过久。
异常兜底：回调加查单双保险；失败原因分层统计与报警。

接入需要多久

取决于你的系统成熟度与业务复杂度。标准电商与数字商品通常可快速完成下单、支付、回调、查单闭环；如涉及代付、分账、复杂风控与对账自动化，建议按模块分阶段上线。

上线前自检清单

所有请求与回调均已验签，密钥只在服务端
回调已实现幂等、可重试、状态机合法迁移
订单状态以回调与查单为准，不依赖前端跳转
失败原因可观测：日志、监控、告警、追踪ID
对账方案已确定：差异处理流程可落地
风控字段已接入：IP、设备、用户标识等可用于风控策略

获取接入资料与技术支持

如果你希望快速对接菲律宾本地支付、提升支付成功率并获得稳定的订单闭环能力，直接联系币付获取 API 文档、测试环境、参数规范、回调示例与联调支持。

品牌：币付 Bifu Pay
客服 Telegram：@Bifuapp
客服邮箱：[email protected]