> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thedecard.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 申请 KYC

> 一次 API 调用把用户 KYC 信息提交给 DCS，拿到 kycTicketId，后续开卡凭此工单；支持 Sumsub Share Token 与证件文件上传两种方式。

* **方式一：Sumsub Share Token** —— 用户已在接入机构自建的 Sumsub 完成认证，直接把 Share Token 交给 DCS，免传证件文件；
* **方式二：证件文件上传** —— 由接入机构自行收集证件并上传给 DCS。

两种方式创建同一种 KYC 工单，状态机与查询/回调完全一致。

## 📄 正文

无论您是交易所、钱包还是平台方，都可以通过一次 API 调用把用户 KYC 信息提交给 DCS——这是为该用户开卡前的必要一步。DCS 作为新加坡 MAS 持牌发卡机构，会安全接收资料、按反洗钱（AML）规则评估风险，并通过 Webhook 回传认证结果。

## 谁做什么

| 步骤               | 谁做   | 说明                                                       |
| ---------------- | ---- | -------------------------------------------------------- |
| 收集用户身份/职业信息      | 接入机构 | Sumsub 路径：在自建 Sumsub 完成认证得到 Share Token；上传路径：准备证件文件与职业信息 |
| 上传文件、提交 KYC 申请   | 接入机构 | 走上传路径时先换取 S3 预上传 URL、把文件 PUT 上去，再调 `apply-kyc`           |
| 证件核验、AML 风控、人工复核 | DCS  | 接收后异步处理                                                  |
| 回传状态与结果          | DCS  | 通过查询接口或 `KYC_TICKET` Webhook                             |

## 前置条件

* 已持有企业（Enterprise）的 ApiKey / SecretKey，参见[鉴权指南](../../integration-resources/authentication)。
* 已创建用户，拿到 `customerId`，参见[创建用户](../users/create-customer)。
* **使用 Sumsub**：已在自建 Sumsub 与 DCS 建立 Sharing Partner 关系（参见 [KYC 服务商说明](../../customer-success/faq-kyc-vendor)），并已取得该用户的 Share Token。
* **走上传路径**：已备好用户证件文件（身份证、护照或驾照等），如涉及地址证明请一并备好。

## 两种方式怎么选

| 场景                   | 推荐方式                   | 关键字段                                     |
| -------------------- | ---------------------- | ---------------------------------------- |
| 已自建 Sumsub 集成        | 方式一：Sumsub Share Token | `sumsubShareToken`                       |
| 未对接 Sumsub，由接入机构自行收料 | 方式二：证件文件上传             | `identifyProofList` / `addressProofList` |

**区分逻辑**：证件文件字段（`identifyProofList` / `addressProofList`）留空时，DCS 跳过相关校验；提交后则按枚举与长度校验。DCS 使用 `sumsubShareToken` 获取用户已在 Sumsub 完成认证的资料。证件文件与 Share Token 可以同时提交，具体处理方式以接入时确认的 KYC 配置为准。两种方式都需要提交**职业信息**（`kycCareerInfo`）。

***

## 方式一：Sumsub Share Token

### 最小请求

`POST /open-api/kyc-ticket/v1/apply-kyc`

```json theme={null}
{
  "kycTicketRef": "kyc-20260617-0001",
  "customerId": "CUST_8f3a...",
  "sumsubShareToken": "_act-xxxxxxxxxxxxxxxxxxxxxx",
  "kycCareerInfo": {
    "employmentStatus": "EMPLOYED",
    "employerName": "Acme Pte Ltd",
    "employmentJobIndustry": "INFORMATION",
    "occupation": "IT_CONSULTANT",
    "jobSeniority": "EXECUTIVE",
    "purposeOfAccount": "DAILY_SPENDING",
    "sourceOfFunds": "EMPLOYMENT",
    "sourceOfFundsCountry": "SG",
    "sourceOfWealth": "EMPLOYMENT"
  }
}
```

> 使用 Sumsub 路径时，`identifyProofList` / `addressProofList` 可留空；DCS 会使用 `sumsubShareToken` 获取用户已认证的证件资料。

***

## 方式二：证件文件上传

### 步骤 1：上传证件文件

身份/地址证明文件不是把图片直接塞进申请请求，而是先换取 S3 预上传链接、把文件 PUT 上去，再在申请时引用返回的 `objectKey`。

调用 `POST /open-api/intent-ticket/v1/generate-pre-upload-url`，`businessType` 传 `CREATE_CARD_KYC`：

```json theme={null}
{
  "fileNames": ["id_front.jpg", "id_back.jpg"],
  "businessType": "CREATE_CARD_KYC"
}
```

接口返回每个文件对应的临时上传 URL 与 `objectKey`。把文件 PUT 到该 URL 后，记下 `objectKey`——下一步的 `identityProofUrl` / `addressProofUrl` 字段填的就是这个 `objectKey`，而不是完整 URL。

### 步骤 2：提交 KYC 申请

`POST /open-api/kyc-ticket/v1/apply-kyc`

```json theme={null}
{
  "kycTicketRef": "kyc-20260617-0001",
  "customerId": "CUST_8f3a...",
  "identifyProofList": [
    {
      "identityProofUrl": "<步骤 1 返回的 objectKey>",
      "identityProofType": "PASSPORT",
      "identityProofSubType": "EMPTY",
      "identityProofIssuedCountry": "SG"
    }
  ],
  "kycCareerInfo": {
    "employmentStatus": "EMPLOYED",
    "employerName": "Acme Pte Ltd",
    "employmentJobIndustry": "INFORMATION",
    "occupation": "IT_CONSULTANT",
    "jobSeniority": "EXECUTIVE",
    "purposeOfAccount": "DAILY_SPENDING",
    "sourceOfFunds": "EMPLOYMENT",
    "sourceOfFundsCountry": "SG",
    "sourceOfWealth": "EMPLOYMENT"
  }
}
```

***

## 请求字段总览

### 通用字段（两种方式都适用）

| 字段                        | 类型     |  必填 | 说明                                                                          |
| ------------------------- | ------ | :-: | --------------------------------------------------------------------------- |
| `kycTicketRef`            | string |  是  | KYC 幂等号；最大 50。同一引用重复提交不会重复建单                                                |
| `customerId`              | string |  是  | 用户 ID；最大 50                                                                 |
| `kycCareerInfo`           | object | 见说明 | 职业信息（见下）。与 `kycCareerInfoEncryption` **至少填其一**                              |
| `kycCareerInfoEncryption` | string | 见说明 | `kycCareerInfo` JSON 的密文，AES-GCM 模式。与 `kycCareerInfo` 至少填其一；两者都有时**优先使用密文** |
| `encryptionIV`            | string |  条件 | AES-GCM 的 IV，用于解密 `kycCareerInfoEncryption`；传密文时必填                          |

### 方式一专用字段

| 字段                 | 类型     |   必填  | 说明                                                  |
| ------------------ | ------ | :---: | --------------------------------------------------- |
| `sumsubShareToken` | string | 方式一必填 | Sumsub Share Token；最大 500。用于获取已认证资料，使用此方式时证件文件字段可留空 |

### 方式二相关字段

| 字段                  | 类型        |   必填   | 说明                  |
| ------------------- | --------- | :----: | ------------------- |
| `identifyProofList` | object\[] | 方式二建议传 | 身份证明文件列表（见下）        |
| `addressProofList`  | object\[] |  方式二可选 | 地址证明文件列表（见下）；最多 5 条 |

<Warning>
  字段拼写注意：外层列表字段名为 `identifyProofList`（identify），其内层字段以 `identityProof*`（identity）开头，两者前缀不同，请严格按本表拼写传参。
</Warning>

<Warning>
  `identifyProofList` 及其内层的 `identityProofType` / `identityProofIssuedCountry` 在接口层面均为**非必填**——这是为了让 Sumsub 路径可以只传 `sumsubShareToken`。但走自行上传证件的路径时，这三项**业务上必须提供**，否则无法完成认证。
</Warning>

**`identifyProofList[]` 身份证明文件**

| 字段                           | 类型     |  必填 | 说明                                                                 |
| ---------------------------- | ------ | :-: | ------------------------------------------------------------------ |
| `identityProofUrl`           | string |  否  | 文件的 `objectKey`（步骤 1 返回）；最大 512。自行上传证件时必须提供                        |
| `identityProofType`          | string |  否  | 枚举：`ID_CARD` / `DRIVERS` / `PASSPORT`；最大 32。自行上传证件时必须提供            |
| `identityProofSubType`       | string |  否  | 枚举：`FRONT_SIDE` / `BACK_SIDE` / `EMPTY`（单面或无正反面之分时传 `EMPTY`）；最大 32 |
| `identityProofIssuedCountry` | string |  否  | 签发国家，2 位 ISO 国家码。自行上传证件时必须提供                                       |

**`addressProofList[]` 地址证明文件**

| 字段                          | 类型     |    必填   | 说明                                                            |
| --------------------------- | ------ | :-----: | ------------------------------------------------------------- |
| `addressProofUrl`           | string |    否    | 文件的 `objectKey`；最大 512。自行上传地址证明时必须提供                          |
| `addressProofType`          | string | 列表非空时必填 | 枚举：`UTILITY_BILL`；最大 32。列表非空而此字段留空会报 `DAPI_SYS_ILLEGAL_PARAM` |
| `addressProofIssuedCountry` | string |    否    | 签发国家，2 位 ISO 国家码                                              |

### `kycCareerInfo` 职业信息（两种方式共同必填）

| 字段                      | 类型     |  必填 | 说明                                           |
| ----------------------- | ------ | :-: | -------------------------------------------- |
| `employmentStatus`      | string |  是  | 就业状态；最大 32                                   |
| `employerName`          | string |  条件 | 雇主名称；当 `employmentStatus=EMPLOYED` 时必填；最大 50 |
| `employmentJobIndustry` | string |  是  | 就业行业；最大 32                                   |
| `occupation`            | string |  是  | 职业；最大 32                                     |
| `jobSeniority`          | string |  是  | 工作资历；最大 32                                   |
| `purposeOfAccount`      | string |  是  | 开户目的；最大 32                                   |
| `sourceOfFunds`         | string |  是  | 资金来源；最大 32                                   |
| `sourceOfFundsCountry`  | string |  是  | 资金来源国家，2 位 ISO 国家码                           |
| `sourceOfWealth`        | string |  是  | 财富来源；最大 32                                   |

> 职业信息为敏感数据。若需端到端加密，把 `kycCareerInfo` 序列化为 JSON 后用 AES-GCM 加密，密文放入 `kycCareerInfoEncryption`、IV 放入 `encryptionIV`，此时可不传明文 `kycCareerInfo`。
> 上述字段由服务端枚举校验，并非任意字符串。完整取值见 [KYC 申请参数字典](./kyc-application-fields)。

## 响应

所有 `/open-api/` 接口共用统一响应结构 `{ code, message, messageDetail, data }`。成功时 `data` 返回新建的 KYC 工单：

```json theme={null}
{
  "code": "SYS_SUCCESS",
  "message": "success",
  "messageDetail": null,
  "data": {
    "kycTicketId": "KYC_1a2b...",
    "kycTicketRef": "kyc-20260617-0001",
    "customerId": "CUST_8f3a...",
    "status": "INIT",
    "createTime": "2026-06-17T08:00:00+08:00"
  }
}
```

> 响应结构说明：业务成败以 `code`（如 `SYS_SUCCESS`）为准，`message` 为简要文案；`messageDetail` 是可选的展示对象（含 `message` / `title` / `type` / `icon` / `action` / `linkTitle` / `linkUrl`），用于前端引导，不应作为判断成败的依据。

<Warning>
  请注意：HTTP 200 + `code=SYS_SUCCESS` 仅代表**申请已受理**，不代表 KYC 通过。提交成功后 `status` 通常为 `INIT`，最终结果需经查询接口或 Webhook 获取。
</Warning>

| 响应字段           | 说明                                                                  |
| -------------- | ------------------------------------------------------------------- |
| `kycTicketId`  | KYC 申请 ID，后续查询/引用以此为准                                               |
| `kycTicketRef` | 回显的幂等号                                                              |
| `customerId`   | 用户 ID                                                               |
| `status`       | KYC 工单状态：`INIT` / `NEED_VERIFY` / `PENDING` / `PASSED` / `REJECTED` |
| `createTime`   | 创建时间，格式 `yyyy-MM-dd'T'HH:mm:ss+08:00`（与平台其他接口一致）                    |

## 跟进认证结果

提交后，KYC 工单会在以下状态间流转（两种方式共用同一状态机）：

| 状态            | 含义     |  终态 | 接入机构下一步                                   |
| ------------- | ------ | :-: | ----------------------------------------- |
| `INIT`        | 信息已提交  |  否  | 等待系统处理                                    |
| `NEED_VERIFY` | 等待人脸认证 |  否  | [获取人脸引导页链接](./h5-kyc-guidance)，引导用户完成人脸认证 |
| `PENDING`     | 审核中    |  否  | 等待系统审核                                    |
| `PASSED`      | 审核通过   |  是  | 可继续后续操作（如申请虚拟卡）                           |
| `REJECTED`    | 审核拒绝   |  是  | 可凭新的 `kycTicketRef` 重新提交                  |

当 `status=REJECTED` 时，[查询 KYC](./query-kyc) 接口与 `KYC_TICKET` Webhook 会返回 `errorCode` 与 `errorMessage` 表示拒绝原因，对应处置见 [KYC 拒绝错误码](./kyc-reject-codes)。

状态更新建议通过 Webhook 订阅获取，避免轮询；详见 [Webhook 数据结构](../webhooks/events-and-schema)。

## 下一步

KYC 通过（`status=PASSED`）后，即可前往 [开卡流程](../cards/card-issuing) 为该用户开卡。若状态停在 `NEED_VERIFY`，先到 [人脸引导页](./h5-kyc-guidance) 引导用户完成人脸认证。