# 开放接口附录：路由字段语义说明

> 本文面向商户技术对接，说明开放接口中与**路由、产品选择**相关的字段含义及相互关系。字段名与 JSON 一致（**camelCase**），与后台 DTO 属性对应。

## 1. 总览：谁决定「用哪条产品」

| 字段 | 适用接口 | 含义（商户视角） |
|---|---|---|
| `payMethodCode` | 统一下单、收银台令牌等 | **支付方式大类**：交互形态或入口类型，如 `qr`、`h5`、`bank_transfer`、`crypto`、`wallet` 等。须与平台为商户开通的 **`payMethodCode` 取值**（管理端/商务约定）一致。 |
| `payTypeCode` | 统一下单、统一代付、收银台等 | **具体产品/SKU**：在某一国家/渠道下的一条可路由产品，对应平台目录中的 **`payTypeCode`**。跨境复杂场景下，**应以附录中该产品为准**补全条件必填字段。 |
| `country` | 统一下单（代收） | **国家**（ISO 3166-1 alpha-2）。与 `payTypeCode`、主数据国家必须一致。 |
| `countryCode` | 统一代付 | 同为国家二字码；代付请求体字段名为 `countryCode`。 |
| `channelCode` | 统一下单、统一代付 | **渠道键**：通常与平台渠道清单中的 **渠道标识（provider key）** 一致。代收为可选路由约束；**代付为必填**（见统一代付接口说明）。 |
| `currency` | 各接口 | ISO 4217；须与该产品支持的币种一致。 |

**关系简述**：

- **`payTypeCode` 是「选产品」的关键字段之一**；同一 `payMethodCode` 下可对应多个 `payTypeCode`（不同国家/不同上游产品）。
- 传了 `payTypeCode` 时，须保证与 `country`/`countryCode`、`payMethodCode`（及代付的 `channelCode`）在平台主数据中**可组成合法路由**，否则接口返回 `PAY_METHOD_*`、`PAY_INTL_*` 等错误码。
- 代收侧若该产品在附录中要求银行/钱包等机构编码，还需按说明传 `instrument.bankCode` 等（见各渠道 `pay_type_code` 附录）。

## 2. 代付字段：`payeeBankCode` / `payeeBranchName` / `payeeIdCard` / `payeeMobile`

以下为**平台统一 DTO 字段名**；在不同国家/产品中语义可能不同，**必须**以对应 `payTypeCode` 的渠道附录为准。

| 平台字段 | 典型用途（示例） |
|---|---|
| `payeeBankCode` | 银行编码、钱包通道码、上游要求的机构标识等 |
| `payeeBranchName` | 支行名称/分行名称；不承载 IFSC 或支行号 |
| `ifsc` | 印度 **IFSC**，统一使用该字段 |
| `payeeBranchCode` | 支行号/分支号 |
| `payeeIdCard` | 税号、**CPF**、**CNPJ** 等税务实名编号 |
| `identityType` / `identityNo` | 普通证件类型和证件号码；`identityType` 使用平台标准枚举：`PASSPORT`、`ID_CARD`、`TAX_ID`、`DRIVING_LICENSE`、`RESIDENCE_PERMIT`、`MILITARY_ID` |
| `payeeEmail` | 收款人邮箱 |
| `payeeMobile` | 钱包手机号、收款手机号等 |
| `ext` | 键值对扩展；键名参与签名（`ext.xxx`）。标准语义字段不得放入 `ext` |

## 3. `Ext` 扩展字典

- 类型为「键值对」；用于承载**未在统一 DTO 顶层单独建模**、但某国/某上游必填的字段。
- 签名时按扁平键 `ext.<键名>` 参与（全小写路径规则以开放接口签名说明为准）。
- 具体键集合见各渠道 **pay_type_code 接入附录**，勿猜测键名。

## 4. 与主数据快照文档的关系

- `website/pay-method-type-master.json`：按代收/代付列出当前平台目录中生效产品的 `payTypeCode` 与渠道键等快照。
- `website/main-data-reference.json`：币种、国家、渠道键与展示名等参考表。
- 上述 JSON **不能替代**各渠道附录中的**条件必填**与 **Ext** 说明；联调以附录 + 实际响应为准。

---

*文档版本：与仓库 `website/` 同步维护。*