> For the complete documentation index, see [llms.txt](https://www.pionex.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://www.pionex.com/docs/api-docs/zh-hant/institution-api/onboarding.md).

# 從這裡開始：接入流程與簽名指南

> 本文档是 **Pionex Institution Open API (v2)** 的「接入流程 + 加密/签名算法」专题指南，帮助机构接入方端到端理解从注册公钥、创建子账户、完成 KYB，到发起入金/出金/兑换的主线流程，并照着实现请求签名。**这不是完整的 API 端点参考**——完整的端点、字段、请求/响应结构见同目录下的 `openapi_institution_v2.yaml`。

机构使用**自己的 API Key（一对 RSA 或 Ed25519 密钥）来接入并运营挂在其名下的子账户（`userId`）：法币入金/出金、稳定币兑换、链上资产、以及交易账户余额。v2 使用公钥签名认证**（RSA 或 Ed25519），并以 **`userId`（UUID）** 标识目标子账户。

| 通用信息     | 值                                                                 |
| -------- | ----------------------------------------------------------------- |
| Base URL | `https://api.pionex.com`                                          |
| 协议       | HTTPS                                                             |
| 数据格式     | JSON                                                              |
| 字段命名     | camelCase（如 `userId`、`clientOrderId`）                             |
| 金额       | decimal 字符串（如 `"100.50"`）——绝不用 float，绝不用最小单位整数                    |
| 时间戳      | 响应体里是**毫秒** Unix 时间戳（`int64`）；签名用的 `timestamp` query 参数是**秒**（见下） |
| 货币代码     | ISO 4217 大写（`"USD"`）；国家代码 ISO 3166-1 alpha-2 大写（`"US"`）           |

***

## 第一部分：接入流程（Onboarding Flow）

### 1. 端到端主线

接入分为两个阶段：

* **Phase 1–4 是接入主线（顺序执行，缺一不可）**：认证 → 创建子账户 → 平台 KYB → 渠道接入。
* 子账户可用后，**入金 / 法币出金 / 链上充币 / 链上提现 / 兑换 / 余额查询是相互独立的能力，可按任意顺序调用**。

![Pionex Institution Open API v2 接入主线流程](https://2358638672-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F22Do5YLaknl8Xug7cEIS%2Fuploads%2Fgit-blob-19d1e2a802187f802357a716f9e2d82b58a2cc91%2Fopenapi_institution_v2_onboarding.svg?alt=media)

> **关键前置门槛（Key gate）：** 所有 `wire/*` 端点（渠道入金接入、入金账户/订单、出金账户、出金）都要求目标 `userId` 的**平台 KYB 先达到 `APPROVED`**，否则返回 `P_PAY_OPEN_API_INTERNAL_KYB_NOT_APPROVED`。

### 2. 分步流程

#### Phase 1 — Authentication（认证）

向 Webot 注册你的**公钥**，取得 API Key（形如 `webot_xxxxxxxx`），并实现请求签名。私钥自持。详见[第二部分](#第二部分加密--签名算法authentication--signing)。

#### Phase 2 — Create Sub-Account（创建子账户）

```
POST /api/v2/institution/user/create
```

创建挂在你机构名下的子账户，按 `clientId` 幂等。请求体：`clientId`（必填，幂等键，≤64）、`email`（必填，≤64）、`entityType`（必填，`CORPORATE`/`INDIVIDUAL`）、`remark`（选填）。响应返回 `data.userId`。后续所有针对该子账户的操作都用这个 `userId`。

> 若返回 `P_PAY_OPEN_API_SUB_USER_ACCOUNT_CREATE_FAILED`，表示子账户已创建但未完成初始化，`data.userId` 会返回已创建的 id，用**完全相同**的请求重发以完成初始化。

用 `GET /api/v2/institution/users` 可列出所有子账户，获取 `userId`。

#### Phase 3 — Platform KYB（平台 KYB）

```
POST /api/v2/institution/kyb/create      # 提交
GET  /api/v2/institution/kyb             # 查询状态
```

提交一次公司/代表人信息，**必须达到 `APPROVED` 后**才能进行任何渠道入金接入。一个 `userId` 只有一份平台 KYB 申请；审核中重复提交会更新它，一旦 `APPROVED` 就不能再提交（返回 `P_PAY_OPEN_API_KYB_ALREADY_APPROVED`）。

提交体结构：

```json
{
  "userId": "88001234-....",
  "subject": { "fields": [ { "key": "subject.legalNameEn", "value": "Acme Ltd." } ] },
  "representatives": [ { "representativeRef": "PERSON-01", "fields": [ { "key": "representative.firstName", "value": "..." } ] } ],
  "documents": [ { "purpose": "subject.sourceOfFundsProof", "fileId": "...", "scope": "SUBJECT" },
                 { "purpose": "representative.passport", "fileId": "...", "scope": "REPRESENTATIVE", "representativeRef": "PERSON-01" } ]
}
```

提交时通过验证（key 合法性 + 无条件必填 + 枚举）返回 `SUBMITTED`；否则返回 `P_PAY_OPEN_API_INVALID_ARGUMENT` 且不落库。

#### Phase 4 — Channel Onboarding（渠道接入 / 渠道 KYB）

```
GET  /api/v2/institution/wire/deposit/account/requirements   # 先查要求
POST /api/v2/institution/wire/deposit/account/create         # 再按要求提交
GET  /api/v2/institution/wire/deposit/account                # 查接入状态
```

平台 KYB 批准后，为某个渠道接入一个入金账户。**`channel` 目前支持 `fvbank`、`straitsx`**。渠道字段是**动态的**——**先调 `requirements`**，再按返回的 `Requirement` 项填写，不要硬编码字段清单。提交后仅返回接入 `status`，不逐项列出缺失，需再调 `requirements` 得知还缺什么。**文档（documents）每次都要完整提交。**

#### 子账户可用后的独立能力

| 能力                       | 关键端点                                                         | 说明                                       |
| ------------------------ | ------------------------------------------------------------ | ---------------------------------------- |
| Deposit 入金               | `GET .../wire/deposit/accounts`、`.../orders`、`.../order`     | 查入金账户（拿到汇款指令 `instructions[]`）与入金订单      |
| Fiat Payout 法币出金         | `.../wire/payout/account/*` → `.../wire/payout/order/create` | 先建 payee 账户，**等其状态到 `AVAILABLE`**，再提交出金  |
| On-chain Deposit 链上充币    | `GET .../asset/address`                                      | 查询指定 `currency`+`chain` 的子账户充币地址（按子账户隔离） |
| On-chain Withdrawal 链上提现 | `POST .../asset/withdraw`、`POST .../addressBook`             | **先把地址加入白名单/地址簿**，再提现                    |
| Convert 兑换               | `POST .../convert/order/create`                              | 稳定币/币种兑换                                 |
| Balances 余额              | `GET .../account/balances`                                   | 交易账户余额                                   |

### 3. KYB 两步走：平台 KYB vs 渠道 KYB 的字段来源差异

接入本质是**两步 KYB**，两者字段来源不同，这是最容易搞混的地方：

| 维度                     | 平台 KYB（`POST /kyb/create`）                                                                                 | 渠道 KYB（`wire/deposit/account/*`）                                                         |
| ---------------------- | ---------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| 字段来源                   | **固定、文档化的字段清单**——照本文档 [Platform KYB Field Reference](#附录平台-kyb-字段参考platform-kyb-field-reference) 填，不通过端点获取 | **动态**——先调 `GET .../wire/deposit/account/requirements`，按返回的 `Requirement` 项填             |
| 前置条件                   | 无（是主线第 3 步）                                                                                                | 平台 KYB 必须先 `APPROVED`                                                                    |
| `channel`              | 不涉及                                                                                                        | 目前 `fvbank`、`straitsx`                                                                   |
| 判定是否提交某项               | 按字段的 M/C/O 标记（Mandatory/Conditional/Optional）                                                              | 按 `Requirement.mode`：`REQUIRED`/`OPTIONAL`/`CONDITIONAL`（`CONDITIONAL` 不确定时建议提交，最终由渠道判定） |
| country / businessType | 在 `subject.*` 里显式提供                                                                                        | **不要传** `country`/`businessType`，它们沿用平台 KYB 的 `subject.country`/`subject.businessType`   |
| 文档                     | `documents[]`，先上传取 `fileId` 再引用                                                                            | 同样先上传取 `fileId`；`kind=DOCUMENT` 的项通过 `fileId` 引用，**文档必须每次完整提交**                          |

渠道 `Requirement` 结构：`{ key, kind (FIELD|DOCUMENT), mode (REQUIRED|OPTIONAL|CONDITIONAL), label, regex, example, enumValues[] }`。`regex`/`example`/`enumValues` 仅用于客户端校验与提示。requirements 只返回该渠道**还缺**的项（已提供的省略）；代表人按 `representativeRef` 分组填各自的 `fields`/`documents`。

### 4. 状态机速查

理解各状态有助于判断流程推进：

| 状态机                               | 取值                                                                                                              | 说明                         |
| --------------------------------- | --------------------------------------------------------------------------------------------------------------- | -------------------------- |
| **平台 KYB 状态**                     | `SUBMITTED` / `PENDING` / `SUPPLEMENT_REQUIRED` / `APPROVED` / `REJECTED`                                       | 只有 `APPROVED` 才解锁 `wire/*` |
| **渠道接入状态**                        | `NOT_CREATED` / `SUBMITTED` / `IN_REVIEW` / `ACTION_REQUIRED` / `APPROVED` / `REJECTED`                         | `NOT_CREATED` 表示尚未接入（非错误）  |
| **入金账户状态**（DepositAccount.status） | `PENDING`（尚不可汇款） / `ACTIVE`（可汇款） / `UNAVAILABLE` / `CLOSED`                                                     |                            |
| **入金订单状态**（DepositOrderStatus）    | `PENDING` / `CREDITED`（已入账未结算） / `COMPLETED`(终态) / `FAILED`(终态) / `CANCELED`(终态)                                |                            |
| **出金账户状态**（PayoutAccount.status）  | `IN_REVIEW` / `AVAILABLE` / `NEEDS_UPDATE` / `UNAVAILABLE` / `DELETED`                                          | 需到 `AVAILABLE` 才能发起出金      |
| **出金订单状态**（PayoutOrderStatus）     | `PENDING` / `IN_REVIEW` / `PROCESSING` / `COMPLETED`(终态) / `FAILED`(终态) / `RETURNED` / `REFUNDING` / `REFUNDED` |                            |

> 业务失败以 HTTP `200` + `result: false` 返回。只有认证层例外：`401`（认证失败）、`400`（请求体无法读取）。终态订单在非成功状态下会带 `reason` 对象 `{ code, message, retryable }`。

***

## 第二部分：加密 / 签名算法（Authentication & Signing）

除少数明确标注的端点外，每个请求都用你的机构 API Key 和一个**签名**来认证。申请 API Key 时向 Webot 注册你的**公钥**，私钥自持。

### 1. 两个请求头

| 请求头           | 说明                                               |
| ------------- | ------------------------------------------------ |
| `X-APIKEY`    | 你的 API Key，形如 `webot_xxxxxxxx`，用于查找你注册的公钥。       |
| `X-Signature` | 对下面的 canonical string 签名后的结果，做 **Base64（标准编码）**。 |

### 2. 两种密钥类型与签名方式

签名算法由**你注册的公钥类型**决定——**不是**每个请求自选。支持两种密钥类型：

| 密钥类型        | 如何签名                          | 备注                                                                   |
| ----------- | ----------------------------- | -------------------------------------------------------------------- |
| **RSA**     | 对 **SHA-256** 摘要做 **RSA-PSS** | 2048–4096 bit 密钥。salt 长度推荐 32（20 / 32 / 64 均可接受）。**不是** PKCS#1 v1.5。 |
| **Ed25519** | **直接**对消息字节签名                 | **不要**预哈希——EdDSA 内部已含 SHA-512。                                       |

* 公钥以 **PKIX/SPKI** 形式注册（`-----BEGIN PUBLIC KEY-----`）。PKCS#1 的 "RSA PUBLIC KEY" 以及其他算法（ECDSA、DSA…）不接受。
* RSA 参考实现：
  * Go：`rsa.SignPSS(rand, priv, crypto.SHA256, sha256(msg), nil)`
  * OpenSSL：`-sigopt rsa_padding_mode:pss`

### 3. 必填 query 参数 `timestamp`

| 参数          | 类型      | 说明                                                              |
| ----------- | ------- | --------------------------------------------------------------- |
| `timestamp` | integer | 当前时间，**秒**级 Unix。每个签名请求都必填，且**参与签名**。必须在服务器时间 **±5 秒**内，否则请求被拒。 |

> `timestamp` 放在 **query string** 里，**即使是 `POST`**（POST 的业务数据在 JSON body）。**没有** `client_id` / nonce 参数。

### 4. canonical string 构造

对下面这个字符串签名：

```
{sub_path}:{sorted_query_string}:{request_body}:{timestamp}
```

| 段                     | 构造方式                                                                                                                                                                                                                                                                                    |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `sub_path`            | 请求路径，**原样**（不 URL 编码），如 `/api/v2/institution/account/balances`。                                                                                                                                                                                                                         |
| `sorted_query_string` | 对每个 key 和 value **分别**按 `encodeURIComponent` 语义 percent-encode——**不转义** `A-Za-z0-9 - _ . ! ~ * ' ( )`，十六进制**大写**，空格用 `%20`（不要用 form-encoding 的 `+`）。各自拼成 `key=value` 后，**对这些 `key=value` 字符串整体排序**，再用 `&` 连接。**所有 query 参数都参与**——`timestamp` 加上业务参数（如 `userId`）；重复的 key 保留，并按 value 排序。 |
| `request_body`        | `POST` 带 JSON body：**原始 body 原样**（不重新序列化）。`GET`：空串（所以 canonical string 里出现 `::`）。                                                                                                                                                                                                       |
| `timestamp`           | 同一个秒值，在末尾**再拼一次**。                                                                                                                                                                                                                                                                      |

**官方示例：**

```
GET  (no body):   /api/v2/institution/account/balances:timestamp=1785706000&userId=88001234::1785706000
POST (JSON body): /api/v2/institution/kyb/create:timestamp=1785706000:{"userId":"88001234"}:1785706000
```

然后 `X-Signature = base64( sign( canonical_string ) )`，与 `X-APIKEY` 一起发送。

> 最常见的接入错误是搞错某个参数的来源（query 还是 body），务必按上表核对。

### 5. 权限 Scopes

每个 API Key 在注册时被授予一个或多个 **scope**（默认 `read`）。每个端点都要求某个 scope；缺权限的请求以 `P_PAY_OPEN_API_PERMISSION_DENIED` 拒绝，**不会进入业务逻辑**。

* **读类端点**（`GET` 查询——余额、订单、记录、requirements、状态、列表）需要 **read**。
* **改状态端点**（`POST` create/submit/update/delete——子账户与 KYB 接入、出金、链上提现、兑换、地址簿与文件写入）需要对应的 **write** scope。

联系 Webot 授予你的 key 所需 scope；key 上的 scope **不能由调用方自行更改**。

### 6. `userId` 参数规则

除公共/自身端点（**create user**、**list users**、**`asset/currencies`**）外，**每个端点都要传 `userId`**（目标子账户的 UUID）：

| 请求形态                        | `userId` 放在哪                            |
| --------------------------- | --------------------------------------- |
| GET 请求                      | **query string**（参与签名）                  |
| POST 请求（JSON body）          | **JSON body** 里                         |
| 文件上传（`multipart/form-data`） | **query string**（body 是 multipart，放不进去） |

`userId` 从 \[List Sub-Accounts] 或 \[Create Sub-Account] 的响应获取。

### 7. 基础错误码

| 错误码                                              | 说明                                       |
| ------------------------------------------------ | ---------------------------------------- |
| `P_PAY_OPEN_API_INVALID_ARGUMENT`                | 请求参数缺失或非法。                               |
| `P_PAY_OPEN_API_UNAUTHENTICATED`                 | 认证失败（缺 key、签名错等）。返回 HTTP `401`。          |
| `P_PAY_OPEN_API_PERMISSION_DENIED`               | API Key 缺此端点权限。                          |
| `P_PAY_OPEN_API_NOT_FOUND`                       | 资源不存在，或不属于该用户。                           |
| `P_PAY_OPEN_API_ALREADY_EXISTS`                  | 资源已存在（如地址已在地址簿）。                         |
| `P_PAY_OPEN_API_SERVICE_UNAVAILABLE`             | 依赖暂不可用，稍后重试。                             |
| `P_PAY_OPEN_API_TIMEOUT`                         | 请求超时，稍后重试。                               |
| `P_PAY_OPEN_API_INTERNAL_ERROR`                  | 内部错误。                                    |
| `P_PAY_OPEN_API_OPERATION_NOT_SUPPORTED`         | 渠道不支持此操作。不要重试。                           |
| `P_PAY_OPEN_API_CHANNEL_NOT_SUPPORTED_IN_REGION` | 请求的 `channel` 对你的接入不可用。不要用同一 channel 重试。 |
| `P_PAY_OPEN_API_INTERNAL_KYB_NOT_APPROVED`       | 平台 KYB 尚未 `APPROVED`，`wire/*` 前置门槛。      |

***

## 附录：平台 KYB 字段参考（Platform KYB Field Reference）

> 平台 KYB 字段清单**固定、文档化**，适用于在 **香港（HK）** 或**其他法域**注册的公司。以下为 `POST /kyb/create` 接受的规范字段与文档。完整字段的 schema 亦见 `openapi_institution_v2.yaml`。

**必填标记：** **M** = Mandatory（缺失即校验失败 `P_PAY_OPEN_API_INVALID_ARGUMENT`）；**C** = Conditional（满足描述里的触发条件时必填）；**O** = Optional（提供加速审核，缺失不阻断）。`HK`/`其他` 列给出各法域（`subject.country`）的标记，`N/A` 表示该法域忽略此字段。文件以 `documents[]` 提交，用文档的规范 key 作 `purpose`，值是 `fileId`。

### Subject 字段（`subject.*`）

| Key                                                        |  HK |  其他 | 规则                                                                                                                                                                                                          |
| ---------------------------------------------------------- | :-: | :-: | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `subject.country`                                          |  M  |  M  | 注册法域，ISO alpha-2 国家码，如 `HK`。                                                                                                                                                                                |
| `subject.legalNameEn`                                      |  M  |  M  | 法定英文名，≤200，须与注册文件完全一致（含 `Limited`/`Ltd.`/`Inc.` 后缀）。非拉丁名需官方英译。                                                                                                                                              |
| `subject.legalNameCn`                                      |  O  | N/A | 法定中文名，≤100。HK 以中文注册者应提供；其他 不适用。                                                                                                                                                                             |
| `subject.registrationNo`                                   |  M  |  M  | HK：商业登记号；其他：IRS EIN（格式 `XX-XXXXXXX`）。≤32。                                                                                                                                                                   |
| `subject.registrationNoType`                               |  M  |  M  | `BRN`(HK) / `EIN`(其他)，须与 `subject.country` 匹配。                                                                                                                                                              |
| `subject.businessType`                                     |  M  |  M  | 组织形式（见枚举）。也决定 其他 需要哪份章程文件。                                                                                                                                                                                  |
| `subject.incorporationDate`                                |  M  |  M  | `yyyy-MM-dd`。成立 < 6 个月可能进入强化尽调。                                                                                                                                                                             |
| `subject.incorporationState`                               | N/A |  M  | 其他 州代码（如 `DE`、`CA`），仅 其他。                                                                                                                                                                                   |
| `subject.email`                                            |  M  |  M  | 官方业务邮箱，≤128。免费邮箱域（gmail/qq/163…）触发人工审核。                                                                                                                                                                     |
| `subject.phone.countryCode`                                |  C  |  C  | 国际区号不带 `+`（如 `852`、`1`）。提供电话时必填。                                                                                                                                                                            |
| `subject.phone.number`                                     |  C  |  C  | 提供电话时必填，≤20。                                                                                                                                                                                                |
| `subject.website`                                          |  O  |  O  | 须含 scheme（`https://`），≤256。电商/平台类推荐。                                                                                                                                                                        |
| `subject.registeredAddress.addressLine2`                   |  O  |  O  | 房/层/单元，≤200。                                                                                                                                                                                                |
| `subject.registeredAddress.city`                           |  M  |  M  | ≤100。                                                                                                                                                                                                       |
| `subject.registeredAddress.state`                          |  O  |  M  | 2 字母州代码（如 `NY`）。其他 必填；HK 可省。                                                                                                                                                                                |
| `subject.registeredAddress.postalCode`                     |  O  |  M  | 其他 必填；HK 无邮编。                                                                                                                                                                                               |
| `subject.registeredAddress.countryCode`                    |  M  |  M  | ISO 3166-1 alpha-2。                                                                                                                                                                                         |
| `subject.operatingAddressSameAsRegistered`                 |  M  |  M  | `true`/`false`。`true` 时省略 `operatingAddress`。                                                                                                                                                               |
| `subject.operatingAddress.*`                               |  C  |  C  | 子字段同 `registeredAddress`。当上者为 `false` 时必填。                                                                                                                                                                  |
| `subject.businessDescription`                              |  M  |  M  | 产品/服务的具体描述，≤500。含糊词（"trading"、"consulting"）会被要求补充。                                                                                                                                                          |
| `subject.accountPurpose.cryptoTrading` 等                   |  O  |  O  | 各 `accountPurpose.*` 为 `true`/`false`：`cryptoTrading`/`fiatDeposit`/`fiatWithdrawal`/`cardIssuing`/`crossBorderPayment`/`fxConversion`/`payroll`/`other`。至少一个应为 `true`；`other` 在 `businessDescription` 里说明。 |
| `subject.monthlyDepositLimit.amount`                       |  M  |  M  | decimal 字符串，≤2 位小数，建议 USD。                                                                                                                                                                                  |
| `subject.monthlyDepositLimit.currency`                     |  M  |  M  | ISO 4217。                                                                                                                                                                                                   |
| `subject.monthlyWithdrawalLimit.amount`                    |  M  |  M  | decimal 字符串，≤2 位小数。                                                                                                                                                                                         |
| `subject.monthlyWithdrawalLimit.currency`                  |  M  |  M  | ISO 4217。                                                                                                                                                                                                   |
| `subject.pepDeclaration.hasPepRelation`                    |  M  |  M  | `true`/`false`。董事/股东/UBO（或近亲）是否为政治敏感人物。                                                                                                                                                                     |
| `subject.pepDeclaration.description`                       |  C  |  C  | `hasPepRelation = true` 时必填，≤500（姓名、职位、任期）。                                                                                                                                                                 |
| `subject.ownershipDeclaration.hasShareholderOver25Percent` |  C  |  C  | `true`/`false`。未提交股权结构证明文件时必填。为 `true` 时 `representatives[]` 须含至少一个 `role.responsibility = ULTIMATE_BENEFICIAL_OWNER`。                                                                                      |
| `subject.ownershipDeclaration.hasNomineeShareholder`       |  O  |  O  | `true`/`false`。为 `true` 须披露最终受益人。                                                                                                                                                                           |
| `subject.highRiskCountryExposure.involved`                 |  O  |  O  | `true`/`false`。业务是否涉及 FATF 高风险法域。                                                                                                                                                                           |
| `subject.highRiskCountryExposure.description`              |  C  |  C  | `involved = true` 时必填，≤500。                                                                                                                                                                                 |
| `subject.termsAgreed`                                      |  M  |  M  | 须为 `true`，否则申请被拒。                                                                                                                                                                                           |
| `subject.dataUsageAgreed`                                  |  M  |  M  | 须为 `true`（授权第三方数据核验）。                                                                                                                                                                                       |
| `subject.serviceAgreementType`                             |  M  |  M  | `FULL`/`RECIPIENT`（见枚举）。                                                                                                                                                                                    |
| `subject.signerPersonRefId`                                |  M  |  M  | 须等于被指定为授权签署人的那位的 `representativeRef`。                                                                                                                                                                       |
| `subject.agreedAt`                                         |  M  |  M  | ISO 8601（如 `2026-08-25T10:12:33Z`）。                                                                                                                                                                         |
| `subject.deviceData.ipAddress`                             |  M  |  M  | 签署人同意时的公网 IP（兼容 IPv6），≤45。                                                                                                                                                                                  |
| `subject.deviceData.userAgent`                             |  M  |  M  | 签署人 User-Agent，≤512。                                                                                                                                                                                        |

### Subject 文档（`subject.*`，值为 `fileId`）

| Key                                                                                            |  HK |  其他 | 说明                                                                             |
| ---------------------------------------------------------------------------------------------- | :-: | :-: | ------------------------------------------------------------------------------ |
| `subject.businessRegistrationCertificate`                                                      |  M  | N/A | 商业登记证（BR）。                                                                     |
| `subject.businessFormation`                                                                    |  M  |  M  | 公司注册证书（HK CI / 其他 Certificate of Incorporation）。                               |
| `subject.incorporationFormNnc1`                                                                |  C  | N/A | 法团成立表格 NNC1。**Note 1**。                                                        |
| `subject.annualReturnNar1`                                                                     |  C  | N/A | 周年申报表 NAR1。**Note 1**。                                                         |
| `subject.einConfirmationLetter`                                                                | N/A |  M  | IRS EIN 确认信（CP575 / 147C）。                                                     |
| `subject.bylaws`                                                                               | N/A |  C  | 章程——`businessType` 为 corporation 子类（`B_/C_/CLOSE_/S_CORPORATION`）时。**Note 4**。 |
| `subject.operatingAgreement`                                                                   | N/A |  C  | 章程——`businessType = LLC`，或未提供 businessType 时的合并兜底。**Note 4**。                  |
| `subject.partnershipAgreement`                                                                 | N/A |  C  | 章程——`businessType = LLP`/`LP`/`GENERAL_PARTNERSHIP` 时。**Note 4**。              |
| `subject.registerOfDirectors`                                                                  |  C  |  C  | 董事名册。**Note 2**。                                                               |
| `subject.ownershipProof`                                                                       |  C  |  C  | 股东名册。**Note 2**。                                                               |
| `subject.shareholdingStructureChart`                                                           |  C  |  C  | 股权结构图。**Note 2、Note 3**。                                                       |
| `subject.certificateOfGoodStanding`                                                            | N/A |  O  | 良好信誉证明。                                                                        |
| `subject.financialStatements`                                                                  |  O  |  O  | 财务报表。                                                                          |
| `subject.authorizationLetter`                                                                  |  O  |  O  | 授权书。                                                                           |
| `subject.sourceOfFundsProof`                                                                   |  M  |  M  | 资金来源证明——见 **Note 5**。                                                          |
| `subject.supportiveOther`                                                                      |  O  |  O  | 其他佐证材料。                                                                        |
| `subject.bankStatement` / `utilityBill` / `leaseAgreement` / `taxNotice` / `addressProofOther` |  O  |  O  | 地址证明（银行流水 / 水电费单 / 租约 / 税务通知 / 其他）。                                            |

**条件规则：**

* **Note 1（HK 章程文件）：** `incorporationFormNnc1` / `annualReturnNar1` 至少提交其一。成立超一年优先 `annualReturnNar1`（最新董事/股东/地址）。
* **Note 2（股权与董事）：** `registerOfDirectors` / `ownershipProof` / `shareholdingStructureChart` 至少提交能完整展示董事与股权的其一。若已由 NNC1/NAR1（HK）或章程文件（其他）体现，可省略，此时 `subject.ownershipDeclaration.*` 也可省。
* **Note 3：** 若上述均无法展示完整股权链（如多层控股），补充阶段会要求 `shareholdingStructureChart`。
* **Note 4（其他 章程）：** 按 `businessType` 提交匹配的章程——corporation 子类 → `bylaws`；`LLC` → `operatingAgreement`；`LLP`/`LP`/`GENERAL_PARTNERSHIP` → `partnershipAgreement`。只交一份，匹配真实组织形式。（类型不明时 `operatingAgreement` 作兜底。）
* **Note 5（资金来源）：** 必填。可接受：近 6 个月公司银行流水、审计财报、关键贸易合同+发票、出资证明、投资协议+回单等。允许多份（至少一份）。仅账户余额截图不足——须展示资金形成链条。
* **地址证明：** 当 `operatingAddressSameAsRegistered = false`，或提交的注册文件未载明地址时必填。用上列 `subject.*` 地址证明 key 提供；须为近 3 个月内出具。

### Representative 字段（`representative.*`）

每人一组，用 `representatives[]` 条目的 **`representativeRef` 属性**区分（**不是** `fields[]` 里的 key）。

| Key                                              |  HK |  其他 | 规则                                                                                |
| ------------------------------------------------ | :-: | :-: | --------------------------------------------------------------------------------- |
| `representativeRef`（属性，非 fields key）             |  M  |  M  | 你系统里稳定的每人 id，补充材料时保持不变。`subject.signerPersonRefId` 引用此值。                          |
| `representative.role.responsibility`             |  O  |  O  | **单值**枚举：`ULTIMATE_BENEFICIAL_OWNER`/`AUTHORIZED_REPRESENTATIVE`/`DIRECTOR`。      |
| `representative.firstName`                       |  M  |  M  | 英文名，≤100，须与证件完全一致。                                                                |
| `representative.middleName`                      |  O  |  O  | 英文中间名，≤100，证件有则填。                                                                 |
| `representative.lastName`                        |  M  |  M  | 英文姓，≤100，须与证件一致。                                                                  |
| `representative.fullNameCn`                      |  O  | N/A | 中文名，≤50。HK：证件有中文名则填。                                                              |
| `representative.jobTitle`                        |  M  |  M  | 职位（如 Director、CEO），≤100。                                                          |
| `representative.birthDate`                       |  M  |  M  | `yyyy-MM-dd`，须与证件一致，须 ≥ 18 岁。                                                     |
| `representative.nationality`                     |  M  |  M  | ISO 3166-1 alpha-2。                                                               |
| `representative.ownershipPercentage`             |  C  |  C  | `role.responsibility = ULTIMATE_BENEFICIAL_OWNER` 时必填。`0.01`–`100`，≤2 位小数；穿透实际比例。 |
| `representative.residentialAddress.addressLine1` |  M  |  M  | 实际居住地址（非临时），≤200。                                                                 |
| `representative.residentialAddress.addressLine2` |  O  |  O  | ≤200。                                                                             |
| `representative.residentialAddress.city`         |  M  |  M  | ≤100。                                                                             |
| `representative.residentialAddress.state`        |  O  |  M  | 其他 必填（2 字母州代码）。                                                                   |
| `representative.residentialAddress.postalCode`   |  O  |  M  | 其他 必填。                                                                            |
| `representative.residentialAddress.countryCode`  |  M  |  M  | ISO 3166-1 alpha-2。                                                               |
| `representative.email`                           |  M  |  M  | 每人必填，≤128（用于验证码投递）。                                                               |
| `representative.phone.countryCode` / `.number`   |  O  |  O  | 主要联系人推荐提供。                                                                        |
| `representative.identityDocument.ssn`            | N/A |  M  | 其他：每人个人税号（SSN/ITIN）；HK 不适用。                                                       |
| `representative.identityDocument.idType`         |  M  |  M  | 见枚举。                                                                              |
| `representative.identityDocument.idNumber`       |  M  |  M  | ≤64。                                                                              |
| `representative.identityDocument.issuingCountry` |  M  |  M  | ISO 3166-1 alpha-2。                                                               |
| `representative.identityDocument.issueDate`      |  O  |  O  | `yyyy-MM-dd`。                                                                     |
| `representative.identityDocument.expiryDate`     |  M  |  M  | `yyyy-MM-dd`。长期证件用 `9999-12-31`；已过期证件校验失败。                                        |
| `representative.ownershipAttestedAt`             |  C  |  C  | ISO 8601。`subject.ownershipDeclaration.hasShareholderOver25Percent` 有值时必填。        |

### Representative 文档（`representative.*`，值为 `fileId`）

按 `identityDocument.idType` 路由证件文件（见枚举里的 idType 路由说明）。

| Key                                                         | Req | 说明                                                 |
| ----------------------------------------------------------- | :-: | -------------------------------------------------- |
| `representative.passport`                                   |  C  | 护照照片页（仅正面）——`idType = PASSPORT` 时。                 |
| `representative.idCardFront` / `idCardBack`                 |  C  | 卡式证件正反两面都要——见 idType 路由。                           |
| `representative.driversLicenseFront` / `driversLicenseBack` |  C  | `idType = DRIVERS_LICENSE` 时正反都要。                  |
| `representative.taxIdDocument`                              |  C  | 税号证明（SSN/ITIN），其他 人员随 `identityDocument.ssn` 一起提供。 |
| `representative.proofOfAddress`                             |  C  | 居住地址与证件所载地址不同时必填。                                  |
| `representative.photoHoldingId`                             |  O  | 风控在疑似欺诈时索取。                                        |
| `representative.liveSelfie`                                 |  O  | 同上。                                                |
| `representative.appointmentDocument`                        |  O  | 委任/授权文件。                                           |
| `representative.nameChangeCertificate`                      |  C  | 证件姓名与申报姓名不同时必填。                                    |
| `representative.supportiveOther`                            |  O  | 其他佐证材料。                                            |

### 枚举

* **`subject.country`**：`HK`、`其他`。
* **`subject.registrationNoType`**：`BRN`(HK)、`EIN`(其他)。
* **`subject.businessType`**（单一列表，不按法域拆分）：`B_CORPORATION`、`C_CORPORATION`、`CLOSE_CORPORATION`、`S_CORPORATION`、`LLC`、`LLP`、`LP`、`GENERAL_PARTNERSHIP`、`SOLE_PROPRIETOR`、`TRUST`、`COOPERATIVE`、`NONPROFIT_CORPORATION`、`OTHER`。（`OTHER` 需附描述；每渠道/国家实际允许的子集由 requirements 返回。）
* **`subject.serviceAgreementType`**：`FULL`（直接服务关系）、`RECIPIENT`（仅收款方，无直接关系）。
* **`representative.role.responsibility`**（单值）：`ULTIMATE_BENEFICIAL_OWNER`、`AUTHORIZED_REPRESENTATIVE`、`DIRECTOR`。
* **`representative.identityDocument.idType`**：`PASSPORT`、`DRIVERS_LICENSE`、`NATIONAL_ID`、`STATE_OR_PROVINCIAL_ID`、`PERMANENT_RESIDENCY_ID`、`MATRICULATE_ID`、`MILITARY_ID`、`VISA`。
* **证件文件按 idType 路由：** `PASSPORT` → `passport`；`DRIVERS_LICENSE` → `driversLicenseFront` + `driversLicenseBack`；其余政府证件（`NATIONAL_ID`/`STATE_OR_PROVINCIAL_ID`/`PERMANENT_RESIDENCY_ID`/`MATRICULATE_ID`/`MILITARY_ID`/`VISA`）→ `idCardFront` + `idCardBack`。
* **地址证明**（用哪个 `subject.*` 文档 key）：银行流水 → `bankStatement`；水电费单 → `utilityBill`；租约 → `leaseAgreement`；税务通知 → `taxNotice`；其他 → `addressProofOther`。

### 文件限制

| 限制               | 值                                                       |
| ---------------- | ------------------------------------------------------- |
| 每次提交最大文件数        | 30                                                      |
| 单文件最大字节          | 12,582,912（12 MB）                                       |
| 单次提交总字节上限        | 104,857,600（100 MB）                                     |
| 允许的 content type | `application/pdf`、`image/jpeg`、`image/png`、`image/heic` |

### 角色完整性与跨字段规则

以下任一不满足即以 `P_PAY_OPEN_API_INVALID_ARGUMENT` 拒绝：

* **登记类型匹配法域：** `HK` ⇒ `registrationNoType = BRN`；`其他` ⇒ `EIN`。
* **其他 州必填：** `其他` 需 `subject.incorporationState`。
* **经营地址必填：** `operatingAddressSameAsRegistered = false` 时须提供 `operatingAddress`。
* **每位代表人都有 `email`。**
* **受益人股权：** 当 `hasShareholderOver25Percent = true`（或股权文件显示 ≥25% 持有人）时，至少一位代表人 `role.responsibility = ULTIMATE_BENEFICIAL_OWNER`；每位该角色的 `ownershipPercentage` 在 `(0, 100]`，且总和 ≤ 100。
* **证件未过期**；卡式证件与 `DRIVERS_LICENSE` 须有**背面**文件。
* **年龄 ≥ 18**（由 `birthDate` 判定）。
* **其他 章程文件匹配 `businessType`**（见 Note 4）。
* **其他 每位代表人有个人税号**（`identityDocument.ssn`）。
* **必需公司文档齐全**（按矩阵）；资金来源证明齐全；股权信息可解析（股权文件或 `ownershipDeclaration.*`）。
* **同意项已接受：** `termsAgreed` 与 `dataUsageAgreed` 均为 `true`。