开发者在接入菲律宾GCash支付通道时，常常面临接口说明文档不完整、字段用途模糊、回调规则不清晰等问题，导致系统部署后频繁出错、维护成本高。币付Pay针对这一行业常态，提供了结构严谨、字段清晰、异常容忍度高的接口文档体系，结合实际部署经验，本文将为你梳理币付GCash接口文档的正确理解方式与部署规范，保障你一次集成长期运行。

一、接口文档结构与调用层级

币付GCash收单系统接口文档共分为三个核心层级：

1. 订单创建层：用于下单与二维码生成（/v2/order/create）
2. 支付状态层：用于实时获取订单状态或补单（/v2/order/query）
3. 回调通知层：用于服务器主动通知业务系统（/v2/notify）

每一层均为REST风格的POST请求，支持Content-Type为application/json，参数字段规范一致。

二、字段设计说明（全量说明）

所有字段在签名前需参与签名计算，不允许调换顺序。

三、签名生成规范（核心逻辑）

币付采用 MD5 签名算法，规则如下：

 1. 移除 sign 字段，将其余非空字段按 ASCII 排序 2. 拼接格式 key1=value1&key2=value2... 3. 拼接密钥：...&key=商户私钥 4. 执行 md5 加密，并转为大写 

错误示例：字段顺序不正确、未拼接私钥、使用小写签名等。

四、回调说明与推荐结构

支付完成后，系统将自动向商户配置的 notify_url POST 发送订单状态。

示例数据：

 { "merchant_no": "demo001", "order_no": "T202507030001", "amount": "100.00", "status": "PAID", "sign": "A1B2C3..." } 

说明：商户接收到后需立即验证签名，并在逻辑完成后返回 success 文本，系统才会停止重试。

推荐做法：所有回调记录入库，并设定去重机制（如order_no唯一），确保幂等。

五、错误码说明与处理建议

六、最佳部署建议

1. 所有请求与回调打印原始JSON日志，方便排查
2. 服务端限制同一用户短时间重复创建相同订单
3. 接口签名封装为独立模块，便于维护与复用
4. 在回调处理逻辑前先验证 sign 字段合法性
5. 状态只处理一次，避免重复到账或发货

七、官方支持与文档获取方式

• 接口文档更新地址：TG频道 https://t.me/GcashNativePay
• 人工开通测试权限 / 获取正式密钥：请联系 @Bifuapp
• 开发中如遇接口参数疑问：请邮件联系 [email protected]

币付接口文档以开发者友好为标准，最大化减少理解成本与部署出错率，实现“1天上线，长期稳定”的GCash解决方案。