> ## 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 资料

> 当证件或 KYC 资料到期时，引导用户重新认证（kycApplyMode=H5-RENEWAL / 引导页 type=8）。流程从 kycRenewalRequired=true 开始，并说明认证被拒后的重试方式和解除限制的时点。

## 📄 正文

证件与 KYC 资料都有有效期。到期后用户需要重新完成一次认证，账户才能维持合规、继续正常消费。DCS 会在检测到到期时主动通知您，您只需引导用户在 DCS 托管的 H5 页面上重新采集证件与人脸即可。

更新复用 H5 KYC 的两步流程，区别只在于申请方式为 `H5-RENEWAL`、引导页类型为 `type=8`。

## 什么时候用它

当以下任一条件成立时，说明该用户需要更新 KYC 资料：

* 调用[查询用户 KYC 信息](./kyc-info)返回 `kycRenewalRequired=true`；
* 收到用户级 [`KYC` Webhook](../webhooks/events-and-schema#kyc)，其中 `kycRenewalRequired=true`。

Webhook 的 `kycRenewalType` 会指明需要更新的因子（`POI` 身份证明 / `SELFIE` 人脸），可用于在前端只提示该补的那一项。

> **在更新完成前，该用户的部分操作（如消费）可能被限制。** 请尽早引导用户完成。

## 与其他 KYC 路径的关系

| 您的情况                          | 该走                              |
| ----------------------------- | ------------------------------- |
| 全新用户，接入机构自己采集证件后 API 提交       | [申请 KYC（API 模式）](./apply-kyc)   |
| 全新用户，让他在 DCS 托管页自助填           | [H5 KYC 引导页](./h5-kyc-guidance) |
| **用户资料到期，需重新认证**              | **本页**                          |
| 用户已在 DeCard 托管模式完成过 KYC，想直接复用 | [KYC 信息迁移](./kyc-migration)     |

## 交互流程

更新可能被拒。被拒后该工单进入终态，但用户**仍然需要更新**（`kycRenewalRequired` 仍为 `true`）；此时应重新申请一条新工单引导用户重试，直到通过、`kycRenewalRequired` 变为 `false`。

<Frame>
  <img className="block dark:hidden" src="https://mintcdn.com/dcs-0bf7a937/oUoeUKtwWWK2o-Li/imgs/diagrams/pa-kyc-renewal-light.svg?fit=max&auto=format&n=oUoeUKtwWWK2o-Li&q=85&s=bc3129dbbc6c6c80f25f2a6c6c49a952" alt="KYC 更新交互流程" width="476" height="957" data-path="imgs/diagrams/pa-kyc-renewal-light.svg" />

  <img className="hidden dark:block" src="https://mintcdn.com/dcs-0bf7a937/oUoeUKtwWWK2o-Li/imgs/diagrams/pa-kyc-renewal-dark.svg?fit=max&auto=format&n=oUoeUKtwWWK2o-Li&q=85&s=e491e03dc94eec6faebea74d6349bbe2" alt="KYC 更新交互流程" width="476" height="957" data-path="imgs/diagrams/pa-kyc-renewal-dark.svg" />
</Frame>

## 步骤一：申请更新工单（接入机构做）

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

| 字段             | 类型     | 必填 | 约束  | 说明                     |
| -------------- | ------ | -- | --- | ---------------------- |
| `kycTicketRef` | string | 是  | ≤50 | 接入机构侧业务幂等号，自定义，后续可凭此查询 |
| `customerId`   | string | 是  | ≤50 | 需要更新资料的用户              |
| `kycApplyMode` | string | 是  | ≤20 | 固定 `H5-RENEWAL`        |

```json theme={null}
{
  "kycTicketRef": "kyc-renew-20260728-0001",
  "customerId": "1000000123",
  "kycApplyMode": "H5-RENEWAL"
}
```

<Warning>
  本步会**同步校验该用户当前确实需要更新**。若该用户并不需要更新（`kycRenewalRequired` 不为 `true`），不会建单，直接返回 `DAPI_KYC_RENEWAL_NOT_REQUIRED`。请先通过[查询用户 KYC 信息](./kyc-info)或 Webhook 确认后再调用。
</Warning>

<Warning>
  同一用户同时只允许**一条**处理中（`INIT`）的更新工单；上一条进入终态（`PASSED` / `REJECTED`）后才能再次申请。
</Warning>

## 步骤二：换取更新引导页链接（接入机构做）

**`POST /open-api/card-redirect/v1/guidance-link`**

| 字段                      | 类型     | 必填    | 约束   | 说明                                                         |
| ----------------------- | ------ | ----- | ---- | ---------------------------------------------------------- |
| `type`                  | string | 是     | ≤1   | 固定 `8`（更新 KYC 资料）                                          |
| `customerId`            | string | 是     | ≤50  | 同步骤一                                                       |
| `kycTicketId`           | string | 是     | ≤50  | 步骤一返回的 `kycTicketId`                                       |
| `errorRedirectUrl`      | string | **是** | ≤200 | 更新失败时跳回的错误页。`type=8` 下**必填**，缺失返回 `DAPI_SYS_ILLEGAL_PARAM` |
| `language`              | string | 是     | 长度 2 | `zh` / `en`；非 zh 国家统一映射为 `en`                              |
| `theme`                 | string | 是     | ≤10  | 如 `default`                                                |
| `mode`                  | string | 是     | ≤10  | `light` / `dark`                                           |
| `userAgent`             | string | 是     | ≤300 | 用户浏览器 UA                                                   |
| `successfulRedirectUrl` | string | 否     | ≤200 | 成功后跳转地址                                                    |
| `submitAutoClosed`      | string | 否     | ≤1   | `Y` 提交成功后自动关闭页面 / `N` 不关闭                                  |
| `primaryColor`          | string | 否     | ≤7   | 主色调，如 `#FFFFFF`                                            |

> `type=8` **不需要** `profileId`（仅 `type=7` 申请 KYC-H5 时必填）。

响应 `data` 为字符串，即可发给用户的 H5 URL。链接有时效性；过期且工单仍为 `INIT` 时，可重新调用本接口换取新链接，**不需要**重新申请工单。

## 步骤三：接收结果并按需重试

通过 [`KYC_TICKET` Webhook](../webhooks/events-and-schema) 或主动调 `GET /open-api/kyc-ticket/v1/detail` 获知审核结果：

* **`PASSED`**：更新完成。随后会收到用户级 `KYC` Webhook `kycRenewalRequired=false`，限制解除。
* **`REJECTED`**：本次更新被拒，`kycRenewalRequired` **仍为 `true`**。回到步骤一，用**新的 `kycTicketRef`** 申请一条新工单引导用户重试。

### 工单状态（更新模式）

更新模式下工单只会出现以下三种状态——**不会**出现 `NEED_VERIFY` 或 `PENDING`：

| 状态         | 含义                               | 是否终态 | 接入机构下一步                                                |
| ---------- | -------------------------------- | :--: | ------------------------------------------------------ |
| `INIT`     | 工单已创建，等待用户在 H5 提交；审核中也停留在 `INIT` |   否  | 把 H5 链接发给用户；链接过期可重新调 `guidance-link`                   |
| `PASSED`   | 审核通过，更新完成                        |   是  | 等 `KYC` Webhook 同步 `kycRenewalRequired=false`          |
| `REJECTED` | 审核被拒                             |   是  | `kycRenewalRequired` 仍为 `true`，需用新 `kycTicketRef` 重新申请 |

## 错误码

### apply-kyc-h5（`kycApplyMode=H5-RENEWAL`）

除 [H5 KYC 引导页](./h5-kyc-guidance#apply-kyc-h5-错误码)列出的通用错误码外，更新模式还可能返回：

| 错误码                                | 含义                                   | 触发场景                 |               可否重试              |
| ---------------------------------- | ------------------------------------ | -------------------- | :-----------------------------: |
| `DAPI_KYC_RENEWAL_NOT_REQUIRED`    | customer does not need KYC renewal   | 该用户当前并不需要更新，或用户信息不完整 | ❌ 先确认 `kycRenewalRequired=true` |
| `DAPI_TICKET_APPLY_LIMIT_EXCEEDED` | Ticket application exceeds the limit | 同一用户申请过于频繁，触发进件频控    |             ✅ 退避后重试             |

### guidance-link（`type=8`）

| 错误码                                | 含义                          | 触发场景                                  |
| ---------------------------------- | --------------------------- | ------------------------------------- |
| `DAPI_SYS_ILLEGAL_PARAM`           | System illegal param        | `kycTicketId` 或 `errorRedirectUrl` 为空 |
| `DAPI_KYC_TICKET_NOT_FOUND`        | kyc ticket not found        | 工单不存在 / 归属不符 / 不是更新模式的工单              |
| `DAPI_KYC_TICKET_IS_IN_PROCESSING` | KYC ticket is in processing | 工单已提交、正在处理中，不可重复操作                    |
| `DAPI_KYC_TICKET_ALREADY_PASSED`   | KYC ticket already passed   | 工单已通过                                 |

## 前置条件

* 已拥有企业（Enterprise）的 ApiKey / SecretKey，见[前置准备](../../getting-started/first-steps)。
* 已确认该用户 `kycRenewalRequired=true`，见[查询用户 KYC 信息](./kyc-info)。
* 已配置可接收 `KYC` 与 `KYC_TICKET` 事件的 Webhook 地址，见 [Webhook 配置](../webhooks/configuration)。

## 下一步

* 查询用户当前是否需要更新 → [查询用户 KYC 信息](./kyc-info)
* 复用用户在 DeCard 托管模式已有的 KYC → [KYC 信息迁移](./kyc-migration)
* Webhook 事件与字段 → [事件与数据结构](../webhooks/events-and-schema)