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

**版本日期**：2026-09-29
**适用接口**：`POST /api/PayRequest/UnifiedPay`  
**渠道键**：`vcpay`  
**国家/币种**：`PE / PEN`、`ID / IDR`、`MX / MXN`、`PK / PKR`

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

## 产品编码

| payTypeCode | 上游 trade_type | 说明 | 银行编码 | 身份信息 |
| --- | --- | --- | --- | --- |
| `yape` | `PEW001` | Yape | 否 | 条件 |
| `plin` | `PEW002` | Plin | 否 | 条件 |
| `bank` | `PET000` | Bank Transfer | 条件 | 条件 |
| `cash` | `PEP001` | PagoEfectivo | 否 | 条件 |
| `qris` | `IDT006` | 印尼 QRIS | 否 | 否 |

> `qris` 仅适用于 `ID / IDR`；其余本表产品适用于 `PE / PEN`。

## 请求要点

- 秘鲁产品使用 `currency=PEN`、`countryCode=PE`；印尼 QRIS 使用 `currency=IDR`、`countryCode=ID`。
- `applyAmount`/订单金额仍按平台统一规则使用分；适配器会按 VCpay 文档以最小单位整数提交。
- `payerName`、`payerIdType`、`payerIdNumber` 如商户侧已采集可传入；平台会映射：
  - `ID_CARD` -> `DNI`
  - `PASSPORT` -> `PAS`
  - `RESIDENCE_PERMIT` -> `CE`
  - `TAX_ID` -> `RUC`
- 回调成功平台返回 `SUCCESS`。

### 印尼 QRIS 响应

当 `countryCode=ID`、`currency=IDR`、`payTypeCode=qris` 且 VCpay 返回支付页链接时，平台会在可信 VCpay 页面中提取二维码图片，并通过统一下单响应返回：

- `acquire.qrImageUrl`：`data:image/...;base64,...`，下游可直接设置为 `<img src>`。
- `acquire.redirectUrl`：保留原 VCpay 支付页链接，用作二维码解析失败或客户端不支持 Data URI 时的降级入口。
- `acquire.displayMode`：`qr`。
- `acquire.displaySource`：`vcpay.qris.inline_image`。

`acquire.qrContent` 只用于二维码原始文本；VCpay 返回的是图片，因此该字段为空。二维码解析失败不会把支付页 URL 伪装成二维码，商户应改用 `redirectUrl` 跳转。

部署时需执行 `doc/sql/20260809_vcpay_indonesia_qris_cashier_inline_qr.sql` 启用该渠道的可信页面解析能力。

## 最小示例

```json
{
  "appId": "app_xxx",
  "merchantOrderNo": "M202606280001",
  "applyAmount": 1000,
  "currency": "PEN",
  "countryCode": "PE",
  "payTypeCode": "yape",
  "notifyUrl": "https://merchant.example.com/payNotify",
  "timestamp": "1782672000",
  "nonce": "nonce001",
  "apiVersion": "v1.0",
  "sign": "<merchant-sign>"
}
```

印尼 QRIS 最小示例：

```json
{
  "appId": "app_xxx",
  "merchantOrderNo": "M202608100001",
  "applyAmount": 10000,
  "currency": "IDR",
  "countryCode": "ID",
  "payTypeCode": "qris",
  "notifyUrl": "https://merchant.example.com/payNotify",
  "timestamp": "1786320000",
  "nonce": "nonce002",
  "apiVersion": "v1.0",
  "sign": "<merchant-sign>"
}
```

## 对照资料

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

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

`channelCode=vcpay`、`countryCode=MX`、`currency=MXN`、`payTypeCode=spei`。金额为分整数。`payerPhone` 可选，对应上游 identity，固定 identity_type=PHONE；`payerName` 对应 identity_name。响应 paymentUrl 是支付跳转地址。查询与回调金额同为分。

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

| payTypeCode | 上游 trade_type | 支付方式 |
| --- | --- | --- |
| `easypaisa` | `PK0001` | Easypaisa 钱包 |
| `jazzcash` | `PK0002` | JazzCash 钱包 |

商户传 `channelCode=vcpay`、`countryCode=PK`、`currency=PKR` 和对应 `payTypeCode`。`applyAmount` 为整数分，配置限额为 `1000000–5000000000` 分（`10000–50000000 PKR`）。`payerPhone` 可选，传入时平台按 `identity_type=PHONE` 映射；`payerName` 对应上游付款人姓名。上游返回的支付地址通过统一下单响应的跳转 URL 字段使用，不作为二维码文本。

```json
{
  "appId": "app_xxx",
  "merchantOrderNo": "M202609290001",
  "applyAmount": 1000000,
  "currency": "PKR",
  "countryCode": "PK",
  "channelCode": "vcpay",
  "payTypeCode": "easypaisa",
  "notifyUrl": "https://merchant.example.com/payNotify",
  "timestamp": "1790640000",
  "nonce": "nonce_pk_001",
  "apiVersion": "v1.0",
  "sign": "<merchant-sign>"
}
```

商户签名和回调验签按平台开放接口协议执行；VCpay 的上游签名由平台处理。代收终态以验签后的查询或回调为准。产品 SQL、商户路由与上游权限配置完成后，商户能力查询才会显示实际可用项。上游协议参考 [VCpay Pakistan pay-in](https://doc.vcpay.org/en/pk/payin.html)。