# TopPay 代收 pay_type_code 接入说明

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

## pay_type_code

| pay_type_code | 国家/币种 | 支付方式 | 说明 |
| --- | --- | --- | --- |
| `pix` | BR/BRL | PIX | 巴西收银台 PIX。 |
| `spei` | MX/MXN | SPEI | 墨西哥 SPEI，默认收银台模式；直连由通道配置控制。 |
| `codi` | MX/MXN | CoDi | 墨西哥 CoDi。 |
| `oxxo` | MX/MXN | OXXO | 墨西哥线下 OXXO。 |
| `aggregate` | PE/PEN | Cashier | 秘鲁收银台；平台向 TopPay api-3 下单时不发送 `method`。 |
| `aggregate` | CO/COP | Cashier | 哥伦比亚聚合收银台。 |
| `pse` | CO/COP | PSE | 哥伦比亚 PSE。 |
| `nequi` | CO/COP | NEQUI | 哥伦比亚 NEQUI。 |
| `qr` | VN/VND | BANK_QR | 越南银行二维码。 |
| `momo` | VN/VND | MoMo | 平台路由映射为 `MOMO`；适配器同时支持配置 `VN_MOMO`。 |
| `zalo_pay` | VN/VND | ZaloPay | 上游 `ZALO`。 |
| `wallet` | VN/VND | ViettelPay | 上游 `VTPAY`。 |
| `bank` | VN/VND | Bank API | 上游 `VN_BANKAPI`。 |
| `aggregate` | VN/VND | VNPay | 上游 `VN_PAY`。 |

VN/VND 仍按平台分提交 `applyAmount`，但 TopPay 仅接受正整数 VND，因此金额必须能被 100 分整除。响应 `payData` 是 URL 时作为跳转地址返回，否则作为二维码/支付码原值返回。

## 秘鲁可选付款人字段

PE/PEN 代收的 `payerIdType`、`payerIdNumber`、`payerPhone`、`payerEmail` 均非必填：

- 全部不传时，平台不会向 TopPay 发送对应的 `documentType`、`documento`、`phone`、`email`，这些字段也不参与上游签名。
- 证件类型和号码应成组传入。`payerIdType=ID_CARD/DNI` 时，`payerIdNumber` 去除分隔符后应为 8 位 DNI。
- `payerPhone` 有值时应为以 `9` 开头的 9 位秘鲁本地手机号；平台也接受带 `+51` 前缀的常见写法并在上游边界规范化。
- 格式无效的 DNI 或手机号会作为可选信息省略；平台内部生成的付款人占位证件、电话和邮箱也不会提交给 TopPay。

## 请求示例

```json
{
  "appId": "YOUR_APP_ID",
  "merchantOrderNo": "M202607090001",
  "payTypeCode": "pix",
  "countryCode": "BR",
  "currency": "BRL",
  "applyAmount": 10000,
  "subject": "TopPay PIX test",
  "notifyUrl": "https://merchant.example.com/pay/notify",
  "timestamp": 1783600000,
  "nonce": "random",
  "apiVersion": "1.0",
  "sign": "..."
}
```

## 回调订单号

TopPay 回调中：

- `orderNum` 是平台提交给 TopPay 的订单号。
- `platOrderNum` 是 TopPay 上游订单号。

商户只需要按平台开放接口回调里的 `merchantOrderNo` 和平台订单号处理幂等，不要直接依赖 TopPay 原始字段。

## 状态

TopPay `SUCCESS` 映射成功；`PAY_CANCEL`、`PAY_ERROR` 映射失败；`INIT_ORDER`、`NO_PAY` 映射处理中。

## 文档来源

- TopPay 在线文档采集记录：`doc/支付渠道文档/toppay/toppay_online_collection.md`
- TopPay 专项说明：`doc/支付渠道文档/toppay/toppay接口对接专项说明.md`
- TopPay 越南协议记录：`doc/支付渠道文档/toppay/toppay_vietnam_online_collection_20260815.md`