# shijiepay 代付账户类型与银行编码说明（待部署）

支持越南VN/VND、菲律宾PH/PHP两国，当前均待部署。

越南：`channelCode=shijiepay`，`countryCode=VN`，`currency=VND`；只支持平台标准`payeeType=BANK`，支付产品`payTypeCode=bank`可用于路由选择。实际开通以PayoutCapabilities/商户生效路由为准，官方资料最后采集2026-10-10。

| 平台字段 | 要求 | 上游语义 |
|---|---|---|
| payeeType | BANK | 银行账户；内部路由转换普通钱包APY003，商户不传原始编码 |
| payeeName | 必填 | bankOwner，真实银行账户户名 |
| payeeAccount | 必填 | bankAccount，真实账号，保留前导零 |
| payeeBankCode | 必填 | [越南平台标准银行码](./vietnam-bank-codes.html)，平台转为bankCode |
| payeeBankName | 可选 | 辅助银行名称；未传按现有映射/平台银行标准反查 |
| applyAmount | 正整数分 | 两位小数VND主币amount |

不要求证件、邮箱、手机号、IFSC或支行编码，不生成虚假收款资料。BANK_CARD、PERSONAL_BANK、APY003、APY004不能作为此渠道payeeType。

```json
{
  "appId": "YOUR_APP_ID",
  "merchantOrderNo": "DEMO_SJ_PAYOUT_001",
  "applyAmount": 1000000,
  "currency": "VND",
  "countryCode": "VN",
  "channelCode": "shijiepay",
  "payeeType": "BANK",
  "payeeName": "REAL BENEFICIARY NAME",
  "payeeAccount": "000123456789",
  "payeeBankCode": "VCB",
  "notifyUrl": "https://merchant.example.com/payout-notify",
  "timestamp": "<CURRENT_UTC_UNIX_SECONDS>",
  "nonce": "<UNIQUE_NONCE>",
  "apiVersion": "v1.0",
  "sign": "<MERCHANT_API_SIGNATURE>"
}
```

请求地址`POST /api/PayRequest/UnifiedPayout`，签名使用平台商户开放API密钥，按[平台签名规范](./api-reference.html#signature)生成。示例金额不是合同限额，必须在商户已生效范围内。

官方66家银行已映射67项现有平台标准（LPB/LVPB兼容）。例：CTG→ICB、AGR→VBA、VCAPB→VCCB、WOO→WVN；商户提交左侧平台码。银行页按渠道列出已确认映射，未映射时遵循原值透传策略，不能据透传宣称渠道支持。银行映射查询异常停止下单。分行及编码大小写由平台适配，商户不要手工改为上游码。

**订单号方向：**平台代付提交BatchId对应上游mchOrderId；商户merchantOrderNo是开放接口幂等键。官方提交、查询和回调没有独立上游订单号，平台上游流水可为空，绝不能把本地单号当成渠道流水。

受理成功进入处理中，出款终态通过验签回调或可信查单确认。缺配置/查询失败/验签失败/未知状态不能判为出款失败。提交超时或未知返回先按原订单查询，保留冻结，不自动跨渠道重提。完整商户响应和通知契约见[完整接口参考](./api-reference.html#payout-unified)，银行见[统一目录](./payout-bank-catalog.html#vietnam-platform-bank-code)。

## 菲律宾 PH/PHP

使用UnifiedPayout同一接口，channelCode=shijiepay、countryCode=PH、currency=PHP，applyAmount为正整数分。

| payeeType | 标准 payTypeCode | 必填收款字段 | 银行编码 |
|---|---|---|---|
| BANK | bank | payeeName、payeeAccount、payeeBankCode | [菲律宾平台标准码](./philippines-bank-codes.html)，例如BPIB→GW_BPI |
| GCASH | gcash | payeeName、payeeAccount | 平台转换GCash，商户省略payeeBankCode |
| MAYA | maya | payeeName、payeeAccount | 平台转换maya，商户省略payeeBankCode |
| GRABPAY | grabpay | payeeName、payeeAccount | 平台转换GW_GBY，商户省略payeeBankCode |
| GOTYME | gotyme | payeeName、payeeAccount | 平台转换GW_GOT，商户省略payeeBankCode |

payeeAccount使用真实收款账号，保持原值；不编造资料或把GoTyme银行账号改成手机号。无证件、支行、邮箱要求。payTypeCode可选，由标准账户类型和生效方法解析；如提供必须匹配表中类型。APY001/APY002两个产品由商户生效路由选中，不能作为payeeType或payTypeCode。普通/原生钱包逐机构开通以商户后台和能力查询为准。

```json
{
  "appId":"YOUR_APP_ID",
  "merchantOrderNo":"DEMO_SJ_PH_PAYOUT_001",
  "applyAmount":10000,
  "countryCode":"PH",
  "currency":"PHP",
  "channelCode":"shijiepay",
  "payeeType":"GCASH",
  "payeeName":"REAL BENEFICIARY NAME",
  "payeeAccount":"<REAL_GCASH_ACCOUNT>",
  "notifyUrl":"https://merchant.example.com/payout-notify",
  "timestamp":"<CURRENT_UTC_UNIX_SECONDS>",
  "nonce":"<UNIQUE_NONCE>",
  "apiVersion":"v1.0",
  "sign":"<MERCHANT_API_SIGNATURE>"
}
```

菲律宾银行表97条原始记录对齐86个标准码；QCDF与LAUI关系待确认，不猜测。钱包和银行编码大小写由平台处理；上游Maya银行、Maya钱包、MayaBusiness分开。代付提交/查询/回调mchOrderId仍是我方BatchId，没有独立上游流水时保持空值；受理成功不等于出款成功，未知提交保留冻结按原单查询。BD/PK/ID/IN本次暂不对接。