# TopPay 代付 pay_type_code 接入说明

**渠道键 / channelCode**：`toppay`  
**金额单位**：开放接口 `applyAmount` 仍传分；平台在 TopPay 上游边界转换为主币单位字符串。

## 账户类型与字段

| pay_type_code | 国家/币种 | payeeType | 必填业务字段 | 说明 |
| --- | --- | --- | --- | --- |
| `pix_cpf` | BR/BRL | `PIX_CPF` | `payeeName`, `payeeAccount` | `payeeAccount` 填 CPF 类型 PIX Key；可传 `payeeIdCard` 作为 taxNumber。 |
| `pix_cnpj` | BR/BRL | `PIX_CNPJ` | `payeeName`, `payeeAccount` | `payeeAccount` 填 CNPJ 类型 PIX Key。 |
| `pix_phone` | BR/BRL | `PIX_PHONE` | `payeeName`, `payeeAccount` | `payeeAccount` 填 `+55` 手机号 PIX Key。 |
| `pix_email` | BR/BRL | `PIX_EMAIL` | `payeeName`, `payeeAccount` | `payeeAccount` 填邮箱 PIX Key。 |
| `pix_random` | BR/BRL | `PIX_RANDOM` | `payeeName`, `payeeAccount` | `payeeAccount` 填 EVP/random PIX Key。 |
| `clabe` | MX/MXN | `CLABE` | `payeeName`, `payeeAccount`, `payeeBankCode` | `payeeAccount` 填 CLABE/银行卡/银行账号；`payeeBankCode` 填 TopPay Mexico bankCode。 |
| `bank` | PE/PEN | `BANK` / `PERSONAL_BANK` | `payeeName`, `payeeAccount`, `payeeBankCode`, `payeeBranchCode`, `payeeMobile`, `payeeEmail`, `identityType`, `identityNo` | `payeeBankCode` 填平台秘鲁标准银行码；平台映射为 TopPay bankCode。`payeeBranchCode` 填 accountNumber/CCI。 |
| `yape` | PE/PEN | `YAPE` | `payeeName`, `payeeAccount`, `payeeMobile`, `payeeEmail`, `identityType`, `identityNo` | `payeeAccount` 填 Yape 钱包账号或手机号。 |
| `plin` | PE/PEN | `PLIN` | `payeeName`, `payeeAccount`, `payeeMobile`, `payeeEmail`, `identityType`, `identityNo` | `payeeAccount` 填 Plin 钱包账号或手机号。 |
| `bank` | CO/COP | `BANK` / `PERSONAL_BANK` / `BANK_CARD` | `payeeName`, `payeeAccount`, `payeeBankCode`, `payeeMobile`, `payeeEmail`, `identityType`, `identityNo` | `payeeBankCode` 填 TopPay Colombia bankCode。 |
| `bank` | VN/VND | `BANK` / `PERSONAL_BANK` / `BANK_CARD` | `payeeName`, `payeeAccount`, `payeeBankCode` | 平台映射为 TopPay `accountName`、`bankCard`、`bankCode`；金额必须能整除 100 分并以整数 VND 上送。 |

PE/PEN 格式要求：`payeeMobile` 必须是 9 位且以 `9` 开头的秘鲁手机号；`identityType=ID_CARD` 会映射 TopPay `DNI`，`identityNo` 必须是 8 位 DNI 数字，分隔符会在上游边界规范化后提交。Yape/Plin 钱包代付上游 `bankCode` 固定提交为 `Yape` / `Plin`。

## 请求示例

```json
{
  "appId": "YOUR_APP_ID",
  "merchantOrderNo": "PO202607090001",
  "payTypeCode": "bank",
  "countryCode": "PE",
  "currency": "PEN",
  "applyAmount": 10000,
  "payeeType": "BANK",
  "payeeName": "BENEFICIARY NAME",
  "payeeAccount": "1234567890",
  "payeeBankCode": "002",
  "payeeBranchCode": "00212345678901234567",
  "payeeMobile": "987654321",
  "payeeEmail": "user@example.com",
  "identityType": "ID_CARD",
  "identityNo": "12345678",
  "notifyUrl": "https://merchant.example.com/payout/notify",
  "timestamp": 1783600000,
  "nonce": "random",
  "apiVersion": "1.0",
  "sign": "..."
}
```

## 银行编码

- BR PIX：不传银行编码。
- MX：`payeeBankCode` 填 TopPay Mexico bankCode，例如 TopPay 文档中的 `40012`。
- PE 银行：`payeeBankCode` 填[平台秘鲁标准银行码](./peru-bank-codes.html)，例如 `002`、`003`、`011`、`043`；平台自动映射为 TopPay `BCP`、`Interbank`、`BBVA`、`CrediScotia` 等。完整的 28 家活跃银行映射见该标准页。
- PE 历史名称：TopPay 清单中的 `Financiero` 是 Banco Financiero 的历史旧名；平台代码 `035` 保持 Banco Pichincha，并上送 TopPay `Pichincha`，不发布第二个冲突平台码。
- PE 钱包：Yape/Plin 分别使用 `payeeType=YAPE/PLIN`，适配器固定上送 TopPay `bankCode=Yape/Plin`；商户不需要提交 `payeeBankCode`。
- CO：`payeeBankCode` 填 TopPay Colombia bankCode，例如 `BANCOLOMBIA`、`NEQUI`。
- VN：`payeeBankCode` 填[平台越南标准银行码](./vietnam-bank-codes.html)，例如 `VCB`、`CTG`、`STB`；平台分别映射为 TopPay `VIETCOMBANK`、`VIETINBANK`、`SACOMBANK`。

完整机器可读矩阵见 [`payout-field-requirements.json`](./payout-field-requirements.json)。

## 回调订单号

TopPay 代付回调中：

- `orderNum` 是平台代付批次号。
- `platOrderNum` 是 TopPay 上游代付单号。

商户只需要按平台代付回调中的商户代付单号做幂等，不要把 `platOrderNum` 当商户单号。