# 开放接口附录 - VCpay 代付 `payTypeCode` 接入说明

**版本日期**：2026-09-29
**适用接口**：`POST /api/PayRequest/UnifiedPayout`  
**渠道键**：`vcpay`  
**国家/币种**：`PE / PEN`、`MX / MXN`、`PK / PKR`（印尼产品字段另见代付字段要求总表）

> 巴基斯坦产品为待部署接入说明；当前可用产品仍以商户能力查询及正式配置支持目录为准。

## 产品编码

| payTypeCode | 上游 trade_type | 平台 payeeType | 必填补充字段 |
| --- | --- | --- | --- |
| `bank` | `PEN000` | `BANK` / `PERSONAL_BANK` | `payeeName`、`payeeAccount`、`payeeBankCode`、`identityType`、`identityNo` |
| `yape` | `PEW001` | `YAPE` | `payeeName`、`payeeAccount`、`identityType`、`identityNo` |
| `plin` | `PEW002` | `PLIN` | `payeeName`、`payeeAccount`、`identityType`、`identityNo` |

## 字段映射

- `payeeName` -> `bank_owner`
- `payeeAccount` -> `bank_account`
  - 银行：填写 CCI 账户
  - Yape/Plin：填写钱包手机号
- `payeeBankCode` -> `bank_code`
  - 银行必填，例如 `PEBB04`
  - Yape/Plin 由平台按 `payeeType` 自动填 `PEW001/PEW002`
- `identityType` -> `identity_type`
- `identityNo` -> `identity`
- `ext.bankAccountType` -> `bank_account_type`，支持 `SA` / `CA`，默认 `SA`

身份类型映射：

| 平台 identityType | VCpay |
| --- | --- |
| `ID_CARD` | `DNI` |
| `PASSPORT` | `PAS` |
| `RESIDENCE_PERMIT` | `CE` |
| `TAX_ID` | `RUC` |

## 银行代付示例

```json
{
  "appId": "app_xxx",
  "merchantOrderNo": "PO202606280001",
  "applyAmount": 1000,
  "currency": "PEN",
  "countryCode": "PE",
  "payTypeCode": "bank",
  "payeeType": "BANK",
  "payeeName": "Maria Bank",
  "payeeAccount": "00212345678901234567",
  "payeeBankCode": "PEBB04",
  "identityType": "ID_CARD",
  "identityNo": "12345678",
  "timestamp": "1782672000",
  "nonce": "nonce001",
  "apiVersion": "v1.0",
  "sign": "<merchant-sign>",
  "ext": {
    "bankAccountType": "CA"
  }
}
```

## 钱包代付示例

```json
{
  "appId": "app_xxx",
  "merchantOrderNo": "PO202606280002",
  "applyAmount": 1000,
  "currency": "PEN",
  "countryCode": "PE",
  "payTypeCode": "yape",
  "payeeType": "YAPE",
  "payeeName": "Yape User",
  "payeeAccount": "987654321",
  "identityType": "ID_CARD",
  "identityNo": "12345678",
  "timestamp": "1782672000",
  "nonce": "nonce002",
  "apiVersion": "v1.0",
  "sign": "<merchant-sign>"
}
```

## 对照资料

- 本地采集记录：`doc/支付渠道文档/vcpay/接口文档采集记录_20260628.md`
- 专项说明：`doc/121_VCpay接口对接专项说明.md`

## 墨西哥 MX/MXN（2026-09-12）

| payeeType | payTypeCode | 必填根字段 | 上游语义 |
|---|---|---|---|
| CLABE | clabe | payeeName、payeeAccount、payeeMobile | bank_owner、18 位 CLABE bank_account、identity；trade_type 读取命中产品的 upstream_type_code；bank_code 为独立协议常量 MX0001 |
| BANK / PERSONAL_BANK | bank | payeeName、payeeAccount、payeeMobile、payeeBankCode | bank_owner、8..64 字符 bank_account、identity、bank_code；trade_type 读取命中产品的 upstream_type_code |

金额为 MXN 分整数，identity_type=PHONE 由平台填写。手机号必须放根字段 payeeMobile，不能以 ext 或 identityNo 替代。银行账户使用[墨西哥平台标准银行码](./mexico-bank-codes.html)，例如 MX-BANK-40012 映射为 MXB019。CLABE 不要求银行码。

## 巴基斯坦 PK/PKR（2026-09-29，待部署）

| payTypeCode | payeeType | 上游 trade_type | payeeBankCode |
| --- | --- | --- | --- |
| `easypaisa` | `EASYPAISA` | `PK0001` | 不传，平台填写 `PK0001` |
| `jazzcash` | `JAZZCASH` | `PK0002` | 不传，平台填写 `PK0002` |
| `bank` | `BANK` | `PK0000` | 必填平台巴基斯坦标准银行码 |

商户提交 `channelCode=vcpay`、`countryCode=PK`、`currency=PKR`。`applyAmount` 为整数分，配置限额 `1000000–5000000000` 分（`10000–50000000 PKR`）。`payeeName` 为收款人姓名（2–64 字符），`payeeAccount` 为账号或钱包号（8–64 字符）。所有三种产品都必须在请求根节点传 `identityType=ID_CARD` 与 `identityNo`，CNIC 使用连续 13 位数字或 `5-7-1` 连字符格式；平台向上游固定填写 `identity_type=CNIC`。

银行产品的 `payeeBankCode` 传[巴基斯坦平台标准银行码](./pakistan-bank-codes.html)，例如 `MEEZAN`；平台已核对的编码会映射为 VCpay `bank_code`。未核对映射的银行码会原样提交，由上游决定是否接受，不应理解为已开通该银行。

银行代付最小示例：

```json
{
  "appId": "app_xxx",
  "merchantOrderNo": "PO202609290001",
  "applyAmount": 1000000,
  "currency": "PKR",
  "countryCode": "PK",
  "channelCode": "vcpay",
  "payTypeCode": "bank",
  "payeeType": "BANK",
  "payeeName": "Ali Khan",
  "payeeAccount": "1234567890123456",
  "payeeBankCode": "MEEZAN",
  "identityType": "ID_CARD",
  "identityNo": "12345-1234567-1",
  "timestamp": "1790640000",
  "nonce": "nonce_pk_002",
  "apiVersion": "v1.0",
  "sign": "<merchant-sign>"
}
```

钱包代付把 `payTypeCode` / `payeeType` 改成 `easypaisa` / `EASYPAISA` 或 `jazzcash` / `JAZZCASH`，`payeeAccount` 填对应钱包号，省略 `payeeBankCode`。提交超时或结果未知时先查单，不直接重试出款。产品 SQL、商户路由与上游权限配置完成后，商户能力查询才会显示实际可用项。上游协议参考 [VCpay Pakistan pay-out](https://doc.vcpay.org/en/pk/payout.html)。