# Dfpay 代付接入说明

版本日期：2026-05-28

适用接口：`POST /api/PayRequest/UnifiedPayout`

## 商户侧传参标准

Dfpay 支持银行卡代付与 QR 代付。商户侧只传平台标准 `payeeType`，不要直接传上游 `accounttype`。

| 场景 | `channelCode` | `countryCode` | `currency` | `payeeType` | `payTypeCode` | 必填收款字段 | 平台到上游映射 |
| --- | --- | --- | --- | --- | --- | --- | --- |
| 越南银行卡 | `dfpay` | `VN` | `VND` | `BANK` / `BANK_CARD` / `PERSONAL_BANK` | `dfpay_vn_payout_bank` | `payeeName`、`payeeAccount`、`payeeBankCode` | `accounttype=1`，`cardnumber=payeeAccount`，`bankid=payeeBankCode` |
| 越南 QR | `dfpay` | `VN` | `VND` | `QR_CODE` | `dfpay_vn_payout_qr` | `payeeName`、`payeeAccount` | `accounttype=2`，`bankid=qrcode`，`qrbase64=payeeAccount` |
| 印尼银行卡 | `dfpay` | `ID` | `IDR` | `BANK` / `BANK_CARD` / `PERSONAL_BANK` | `dfpay_id_payout_bank` | `payeeName`、`payeeAccount`、`payeeBankCode` | `accounttype=1`，`cardnumber=payeeAccount`，`bankid=payeeBankCode` |
| 印尼 QR | `dfpay` | `ID` | `IDR` | `QR_CODE` | `dfpay_id_payout_qr` | `payeeName`、`payeeAccount` | `accounttype=2`，`bankid=qrcode`，`qrbase64=payeeAccount` |
| 巴基斯坦银行卡 | `dfpay` | `PK` | `PKR` | `BANK` / `BANK_CARD` / `PERSONAL_BANK` | `dfpay_pk_payout_bank` | `payeeName`、`payeeAccount`、`payeeBankCode` | `accounttype=1`，`cardnumber=payeeAccount`，`bankid=payeeBankCode` |
| 巴基斯坦 QR | `dfpay` | `PK` | `PKR` | `QR_CODE` | `dfpay_pk_payout_qr` | `payeeName`、`payeeAccount` | `accounttype=2`，`bankid=qrcode`，`qrbase64=payeeAccount` |

`payTypeCode` 为可选入参。商户只传 `channelCode=dfpay + countryCode + currency + payeeType` 时，平台会按后台启用的代付产品自动路由；如果同时传 `payTypeCode`，平台会校验该产品是否支持对应的 `payeeType`。

## QR 代付最小示例

```json
{
  "appId": "app_xxx",
  "merchantOrderNo": "PAYOUT202605280001",
  "applyAmount": 10000,
  "currency": "VND",
  "channelCode": "dfpay",
  "countryCode": "VN",
  "payeeType": "QR_CODE",
  "payeeName": "Test Payee",
  "payeeAccount": "base64-or-qr-content",
  "timestamp": "1779950000",
  "nonce": "nonce-value",
  "apiVersion": "v1.0",
  "sign": "merchant-sign"
}
```

## 注意事项

- QR 代付不要传 `payeeBankCode`，平台固定上游 `bankid=qrcode`。
- 银行卡代付必须传 `payeeBankCode`，平台映射为上游 `bankid`。
- `payeeAccount` 在银行卡场景表示银行卡号或银行账号；在 QR 场景表示二维码内容或二维码 base64。
- Dfpay 回调成功 ACK 为纯文本 `OK`，失败返回 `fail`。