菲律宾支付通道 API 对接规划：GCash、Maya 商户支付的授权前提与技术检查

规划菲律宾支付通道时，不能把“接口可以调用”等同于“业务可以上线”。围绕 GCash、Maya 的商户支付项目，企业需要分别确认商户资格、产品权限、接口来源和交易处理机制。先完成授权核验，再安排支付 API 开发，才能减少接口联通后仍需返工的情况。

本文用于技术规划，不代表任何平台的官方准入说明。具体接入要求以客户所选服务方提供的有效协议、授权说明和当前技术文档为准。

一、先明确支付通道与软件的责任边界

支付通道负责什么、软件处理什么，应在立项时写清。客户需自行取得适用于其业务的支付通道，并确认签约主体、交易权限和资金安排；软件系统则依据已获授权的接口组织订单、状态、对账及运营流程。

BD Payment 提供支付系统软件租赁、部署和技术/API 对接，客户使用自己的支付通道。BD Payment 不提供银行账户、电子钱包账户、支付通道、牌照或监管授权，也不能替代 GCash、Maya 或客户所选服务方的审核。

涉及监管、商户管理及资金流转要求时，客户应按自身业务模式向菲律宾当地专业人士核实，不能仅凭软件功能判断业务是否合规。

二、GCash、Maya 商户支付的授权前提

GCash 商户支付对接评估：核对主体与产品范围

评估应从客户实际申请或签约的服务入手，而不是从钱包品牌名称推断权限。建议整理以下材料：

• 商户主体、业务类型、经营场景及对应的审核记录。
• 接口提供方、签约关系及其服务权限说明，确认授权链路可以核验。
• 获准使用的支付产品、使用渠道和适用场景。
• 正式环境开通状态、API 凭据归属、查询与回调能力说明。

拥有个人钱包、商户收款码或测试凭据，不应直接推定为拥有线上 API 收款权限。退款、付款等能力也应逐项确认，不能由收款权限自动延伸。

Maya Business 接入条件核验：区分申请与开通

对 Maya Business 相关项目，应明确当前处于资料提交、审核、测试还是正式启用阶段，并确认实际接入产品及文档版本。具体资料清单由相应服务方确定，不宜套用未经核实的统一要求。

建立“能力—依据—状态”清单：每项能力对应协议、后台权限或书面确认，并标注已确认、待确认、不支持。结算周期、退款范围和争议处理责任也应从有效业务文件核实，不能由接口返回成功推断。

三、支付 API 上线前的技术检查

订单与状态：超时不等于失败

设计商户订单号、系统订单号和通道交易号的映射，统一金额精度、币种、时区及状态含义。待支付、处理中、成功、失败、关闭和退款状态应有明确转换规则，禁止旧通知覆盖已确认的新状态。

请求超时时，通道可能已受理订单。应先按接口能力查询或使用规定的重试机制，不要立即换订单号重新发起支付。查询结果与回调冲突时，按服务方文档确定处理依据，保留异常记录。

支付回调验签：不能只检查来源地址

支付回调验签应严格遵循实际接口的算法、字段排序、编码及密钥规则。验签依赖原始报文时，必须保留原始字节，避免解析或格式化改变签名输入。若协议提供时间戳、随机数或事件编号，应配套校验时效和防重放规则。

验签通过后，仍需核对商户归属、订单号、金额、币种和事件类型。持久化接收记录后，按文档要求应答；耗时操作可转入异步处理。IP 限制只能作为补充，不能代替身份与完整性校验。

API 幂等处理：覆盖请求和业务入账

API 幂等处理不能只做“订单号去重”。应为同一业务操作使用稳定的幂等标识，并在数据库中约束唯一性；同一标识携带不同金额或对象时应拒绝。支付、退款和付款操作需分别定义幂等范围。

面对重复回调与并发查询，应通过事务、条件更新或等效机制保证状态只被有效推进一次，内部账务记录和发货等动作不重复执行。若通道不支持原生幂等参数，应结合本地控制与交易查询处理不确定结果，避免盲目重试。

四、对账、权限与部署如何安排

自动订单匹配可依据交易号、订单号、金额和币种执行；缺少可靠标识时应进入异常队列，不宜仅凭相近金额与时间强行匹配。业务订单、通道交易记录和可获得的结算记录应分层核对，支付成功不等于资金已经结算。

BD Payment 的软件功能可围绕订单、商户、代收付流程、多通道管理、自动订单匹配、财务对账、风险管理、代理商、报表、权限和交易查询配置。具体交易能否执行，仍取决于客户自有通道的授权与接口能力。

部署阶段可评估独立部署或多租户部署，以及标准或定制 API 对接。独立部署需落实运维、备份与密钥管理；多租户部署需检查商户数据、凭据、回调路由和操作权限的隔离，避免跨商户查询或误操作。

五、用验收清单控制上线范围

1. 材料确认：授权范围、接口文档、环境地址、凭据归属及支持联系人完整。
2. 联调测试：覆盖正常支付、超时、重复请求、重复或乱序回调、验签失败及状态冲突。
3. 运营验收：验证对账差异、人工复核、权限审批、日志脱敏和告警流程。
4. 发布准备：确认正式权限与测试环境差异，完成密钥切换，约定异常时暂停新增交易和保留处理中订单追踪的方案。

小结

菲律宾支付通道对接的关键，是把商业授权、技术能力和软件职责分开核实。先完成 GCash、Maya 相关接入条件确认，再落实回调验签、幂等、状态管理和对账，才能形成可验收、可追踪的实施方案。

常见问题 FAQ

1. 有 GCash 或 Maya 账户就能调用商户支付 API 吗？

不能据此判断。需核实账户类型、签约产品、审核状态和正式 API 权限，个人账户或收款工具不必然具备相关能力。

2. BD Payment 能提供菲律宾支付通道吗？

不能。客户使用自己的支付通道，BD Payment 提供软件租赁、部署及技术/API 对接，不提供账户、通道、牌照或监管授权。

3. 收到成功回调后可以直接发货吗？

应先完成验签、订单要素核对和有效状态更新，再按业务风控规则执行幂等发货。存在冲突或可疑信息时，应查询并复核。

4. 测试环境通过是否意味着可以正式上线？

不是。还需确认正式环境权限、凭据、网络配置及业务授权，并核对测试与正式环境的功能差异。

5. 标准 API 与定制 API 如何选择？

先比较客户现有接口与软件标准接口的订单、状态、验签及对账规则。差异较大时再评估定制；定制开发不能替代缺失的产品权限。