币付pay在菲律宾本地支付集成中，开发者最常遇到的三个核心难点：接口结构混乱、支付状态不一致、回调容错率低。本文围绕币付Pay系统架构，深度解读每一个API接口的实际用途、安全性策略与异常场景解决方式，力求为开发者提供完整的稳定集成范式，最大限度减少开发投入与后期维护成本。
一、整体架构图示（逻辑流程）
- 客户端请求服务端生成支付订单
- 服务端调用
/v2/order/create接口，生成二维码链接 - 用户完成支付 → GCash 通知币付 → 币付主动回调商户接口
- 商户收到
/notify回调 → 校验签名 → 标记订单成功 - 如未收到回调，商户调用
/order/query进行补单
二、接口结构与关键字段
| 接口 | 作用 | 方式 | 签名字段 |
|---|---|---|---|
| /v2/order/create | 生成订单 | POST | amount、merchant_no、order_no 等 |
| /v2/order/query | 查询支付状态 | POST | order_no、sign |
| /v2/notify | 异步回调接口 | POST（由平台发起） | status、amount、sign |
| /v2/payout/batch | 商户结算 | POST | batch_no、target、sign |
三、签名机制详解
所有请求和回调都通过 MD5 签名方式加密，保证防篡改、防伪造。签名串为【ASCII顺序排序】后拼接字符串，并加上商户私钥：
def generate_sign(params, app_secret): raw = "&".join(f"{k}={v}" for k, v in sorted(params.items()) if v) + f"&key={app_secret}" return hashlib.md5(raw.encode()).hexdigest().upper() - 签名前所有字段必须排序一致，任何字段错位均会造成签名失败。
- 校验失败将返回
{"code":401,"msg":"签名错误"}。
四、支付状态容错机制
- 主通道：系统主动向商户
/notify回调 - 容错通道：商户可定时轮询
/order/query补查 - 回调最多5次：间隔：5s、15s、30s、1m、3m
- 必须返回 “success”：否则视为回调失败
五、高并发场景优化建议
- 前端创建订单按钮加防抖，禁止重复下单
- 后端处理
/notify回调时建议写入消息队列（Kafka/RabbitMQ） - 对
/order/query设置10秒冷却缓存，避免流量集中
六、常见异常场景与排查
| 异常 | 原因 | 解决建议 |
|---|---|---|
| 订单无回调 | 网络中断或回调地址异常 | 调用 /order/query 后台补单 |
| 签名校验失败 | 字段顺序错误或密钥错 | 打印排序串调试签名逻辑 |
| 结算延迟 | 银行处理时长问题 | 调用结算查询接口 + 邮件联系客服 |
七、开发调试建议
- 开发环境优先接入
ngrok模拟公网回调 - 使用 Postman 调试签名串、参数拼接
- 每个请求记录日志
(入参+签名+响应+返回耗时)
八、币付Pay开发者支持
- 接口文档 PDF：[email protected]
- 最新公告与系统状态：TG频道
- 测试密钥申请：联系 Telegram
@Bifuapp
币付Pay — 高稳定、高成功率的菲律宾支付系统，赋能开发者高效集成与运营。
发表评论
发表评论: