针对菲律宾地区GCash集成时的“接口不统一”“回调不稳定”“签名易错”三大痛点，币付Pay通过结构化API设计与高容错机制提供了更高标准的接入方式。本文将从接口层级结构、签名生成规则、回调控制、异常兜底逻辑四方面系统解析币付Pay接口体系，帮助开发者一次性实现稳定接入，降低后期维护开销。

一、接口结构总览（统一逻辑 + 简化调用）

二、签名机制详解（全字段参与 + 商户密钥）

币付Pay所有接口签名算法统一采用 MD5，并对参数进行ASCII升序排列，形成串后拼接商户密钥，再计算签名。

 # 示例（伪代码）： params = {order_no: 123, amount: 100.00, merchant_no: xxx} raw_string = sort(params) + "&key=商户密钥" sign = md5(raw_string).toUpper() 

• 必须参与签名字段：merchant_no、order_no、amount 等
• 任何一个字段顺序错误、空值未剔除均会导致签名校验失败
• 服务端评测商户签名串和原始字段，一旦不符即返回签名错误

三、回调机制说明（主动通知 + 容错轮询）

回调采用系统主动触发通知商户订单状态，若商户未正确返回success文本，系统会重试：

• 回调频次：最多5次，间隔分别为5s、15s、30s、60s、300s
• 回调字段：order_no、merchant_no、status、amount、sign 等
• 状态值为 SUCCESS 表示支付成功，需商户立即标记订单完成

建议处理方式：

1. 后端接收回调后，先校验签名
2. 再判断 status == 'SUCCESS'，更新订单状态
3. 最后 返回纯文本字符串：success

四、并发控制与异常补救

• 防重复下单：客户端强制前端按钮防抖；服务端基于order_no判断是否重复
• 补单策略：如回调失败或遗漏，调用 /order/query 接口再次确认
• 日志记录：每次请求建议记录 请求体、签名串、响应数据、响应耗时

典型异常场景与排查：

五、开发接入调试建议

• 使用 Postman 测试参数拼接和签名是否正确
• 接入 ngrok 或 frp 实时模拟回调至本地环境
• 强烈建议使用生产测试商户，避免正式资金测试

六、接口版本与更新频率

• 当前使用 v2 版本，为长期支持版本
• 更新频率约每季度一次，向下兼容
• 变更信息将在 TG 群实时发布

七、官方支持与资源获取

• 客服邮箱：[email protected]
• 官方通道通知群：https://t.me/GcashNativePay
• 测试接入资料申请：联系 @Bifuapp

币付Pay接口结构标准、字段清晰、签名稳定，适合高频、高并发GCash支付集成环境。