# yzpay 菲律宾 GCASH 接入说明（待部署）

适用 PH/PHP，渠道 `channelCode=yzpay`。本页为协议接入说明，尚未纳入正式配置快照；实际开通、限额及路由以商户能力查询为准。

| 业务 | 平台标准支付类型 | 上游产品 | 金额范围（分） |
|---|---|---|---|
| 代收 | gcash | 34 | 10000–5000000 |
| 代付 | gcash，账户类型 GCASH | 8601 | 10000–5000000 |

代收通过 [UnifiedPay](./api-reference.html#pay-unified) 提交平台整数分金额。返回付款链接，按链接打开原生 GCASH 支付页，不把链接或链接中的参数当成二维码内容。渠道可能调整应付金额，请以付款页面为准；原订单金额保留，平台按可信实付金额计算最终手续费和入账净额。查询 `MerchantHostedPaymentMethods` 了解实际可用能力，收到平台成功通知后再确认入账。

代付使用标准根字段：

| 字段 | 要求与上游含义 |
|---|---|
| payeeType | GCASH；不要提交上游产品码 8601 |
| payeeName | 必填，完整姓名 → account_holder，最长24字符 |
| payeeAccount | 必填，真实 GCASH 钱包账号 → bank_account，最长24字符 |
| payeeMobile | 必填，真实收款联系人手机号 → account_holder_mobile，最长24字符 |
| payeeBankCode / payeeBankName | 非必填；deposit_bank_code=gcash、deposit_bank=Gcash、acct_type=Gcash 由平台固定映射 |
| identityType / identityNo | 本产品不要求证件；仍须遵守标准字段成对校验 |

手机号原值保留，支持本地/国际输入，不强制商户增删国家码；不要把手机号、账号或证件藏在 ext。此产品仅支持 GCASH，银行列表中的其他机构未开通。平台银行标准对应关系见 [菲律宾机构目录](./philippines-bank-codes.html) 的 GCASH，完整 [银行与钱包目录](./payout-bank-catalog.html)。

代付提交成功仅表示已受理；平台通过可信回调/查单推进终态。超时或结果未知请查询原订单，避免重复出款。原始上游查询 3 成功、4/5 失败；真实回调使用 0/1，平台已统一转换，商户无需处理渠道原始码。

代收查询不返回真实流水时，平台保留流水空值，按活动尝试和已验签金额复核恢复订单；后续真实回调可首次绑定流水。平台重试会生成独立且持久化的短提交号，父订单与商户幂等身份保持不变。使用商户接口响应中的标准订单字段查询，不自行拼接或截断提交号。

渠道异步通知由平台接收，商户 notifyUrl 始终是平台处理后通知商户的地址；yzpay 的可选同步跳转字段长度不足以容纳平台中转地址，本次不发送该字段。商户应依赖异步通知或主动查单确认最终结果。

[完整商户字段表](./api-reference.html#payout-merchant-standard-table) · [快速接入](./api-docs.html)