> ## 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 工单 ID（或申请 KYC 时的幂等键）查询最新的认证状态与结果，并根据状态和拒绝原因决定下一步操作。

## 📄 正文

无论您是交易所、钱包还是平台方，都可以在提交 KYC 申请之后随时查询其处理进度——当前状态、是否需要引导用户补充人脸认证、以及拒绝时的具体原因，便于您在自有系统中实时跟进用户的开卡资格。DCS 作为持牌发卡机构，KYC 审核结果由合规团队与外部供应商共同把关。

查询 KYC 由**接入机构**发起，**DCS** 返回该 KYC 工单的当前快照。

> 本页查的是**某一次认证**（工单）的进度。若您想知道**某个用户**当前的 KYC 概要、以及他的资料是否已到期需要重做，那是另一条接口，见[查询用户 KYC 信息](./kyc-info)。两者都叫「查 KYC」，容易混。

### 前置条件

* 您已持有企业（Enterprise）的 `ApiKey` / `SecretKey`。若尚未领取，请参阅[前置准备](../../getting-started/first-steps)。
* 您已提交过 KYC 申请。若还未申请，请先完成[申请 KYC](./apply-kyc)。

### 步骤

1. 准备 KYC 工单标识：使用申请 KYC 时返回的 `kycTicketId`，或您在申请时传入的幂等键 `kycTicketRef`（接入机构）。
2. 按[鉴权约定](../../integration-resources/authentication)生成请求头，调用查询接口（接入机构 → DCS）。
3. 从响应 `data.status` 读取当前状态并按下表处置（接入机构）：
   * `NEED_VERIFY`：引导用户完成人脸认证，参阅 [H5 人脸引导页](./h5-kyc-guidance)；
   * `PASSED`：可进入开卡流程；
   * `REJECTED`：读取 `errorCode` / `errorMessage` 判断原因，必要时引导用户重新提交。

### 查询 KYC 详情

**`GET /open-api/kyc-ticket/v1/detail`**

#### 查询参数

| 参数             | 位置    | 类型     | 必填 | 说明                                                                         |
| -------------- | ----- | ------ | -- | -------------------------------------------------------------------------- |
| `kycTicketId`  | query | string | 否  | KYC 工单 ID（DCS 申请 KYC 时返回）                                                  |
| `kycTicketRef` | query | string | 否  | KYC 工单幂等字段（接入机构申请时自定义）                                                     |
| `salt`         | query | string | 否  | API 模式使用的校验盐值，具体取值由接入机构与 DCS 在接入时约定；DCS 不参与加解密。H5 模式可忽略；最大长度 64，不传时按空字符串处理 |

> `kycTicketId` 与 `kycTicketRef` 至少需传入其一以定位工单；建议优先使用 `kycTicketId`。

#### 请求示例

```
GET /open-api/kyc-ticket/v1/detail?kycTicketId=200000000456
Host: <api-base>
Content-Type: application/json
X-DAPI-API-KEY: <your-api-key>
X-DAPI-TIMESTAMP: <timestamp-ms>
X-DAPI-NONCE: 12345
X-DAPI-SIGN: <signature>
```

> 完整鉴权头（`X-DAPI-API-KEY` / `X-DAPI-TIMESTAMP` / `X-DAPI-NONCE` / `X-DAPI-SIGN`，并带 `Content-Type: application/json`）的生成方式见[鉴权](../../integration-resources/authentication)。

#### 响应示例

```json theme={null}
{
  "code": "SYS_SUCCESS",
  "message": null,
  "messageDetail": null,
  "data": {
    "kycTicketId": "200000000456",
    "kycTicketRef": "your-kyc-ref-001",
    "customerId": "100000000123",
    "status": "PASSED",
    "createTime": "2025-01-01T12:00:00+08:00",
    "modifyTime": "2025-01-02T09:30:00+08:00",
    "digest": "****1234",
    "kycRenewalRequired": false,
    "kycApplyMode": "H5"
  }
}
```

被拒绝时，`data` 中额外返回 `errorCode` / `errorMessage`：

```json theme={null}
{
  "code": "SYS_SUCCESS",
  "message": null,
  "messageDetail": null,
  "data": {
    "kycTicketId": "200000000456",
    "status": "REJECTED",
    "errorCode": "INVALID_POA",
    "errorMessage": "地址证明无效"
  }
}
```

> 上述 `errorCode` 为示意值，完整取值与含义请参阅[KYC 认证错误码](./kyc-reject-codes)。

#### `data` 字段

| 字段                   | 类型      | 说明                                                                                                                           |
| -------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `kycTicketId`        | string  | KYC 工单 ID                                                                                                                    |
| `kycTicketRef`       | string  | KYC 工单幂等字段                                                                                                                   |
| `customerId`         | string  | 用户 ID                                                                                                                        |
| `status`             | string  | KYC 工单状态，取值见下方状态机表                                                                                                           |
| `createTime`         | string  | 创建时间，格式 `yyyy-MM-dd'T'HH:mm:ss+08:00`                                                                                        |
| `modifyTime`         | string  | 最后更新时间，格式 `yyyy-MM-dd'T'HH:mm:ss+08:00`                                                                                      |
| `digest`             | string  | 加密（脱敏）后的证件号                                                                                                                  |
| `kycRenewalRequired` | boolean | 是否需要 KYC 续期                                                                                                                  |
| `kycApplyMode`       | string  | 申请方式：`API`（API 提交）/ `H5`（H5 页面申请 KYC）/ `H5-RENEWAL`（[更新 KYC 资料](./kyc-renewal)）/ `H5-MIGRATION`（[KYC 信息迁移](./kyc-migration)） |
| `errorCode`          | string  | 拒绝原因错误码，**仅 `REJECTED` 状态返回**                                                                                                |
| `errorMessage`       | string  | 拒绝原因描述，**仅 `REJECTED` 状态返回**                                                                                                 |

#### KYC 工单状态机

| 状态            | 含义        | 是否终态 | 接入机构后续操作                                       |
| ------------- | --------- | :--: | ---------------------------------------------- |
| `INIT`        | KYC 信息已提交 |   否  | 等待系统处理                                         |
| `NEED_VERIFY` | 等待人脸认证    |   否  | 引导用户完成人脸认证，参阅 [H5 人脸引导页](./h5-kyc-guidance)    |
| `PENDING`     | 审核中       |   否  | 等待系统审核                                         |
| `PASSED`      | 审核通过      |   是  | 可进入后续操作（如[开卡](../cards/card-issuing)）          |
| `REJECTED`    | 审核拒绝      |   是  | 读取 `errorCode` / `errorMessage`，必要时重新提交 KYC 申请 |

> **关于拒绝原因**：状态为 `REJECTED` 时，响应 `data` 中会带 `errorCode` 与 `errorMessage`；同一信息也会通过 [`KYC_TICKET` Webhook](../webhooks/events-and-schema) 推送。完整错误码归类（分类 / 可否重试 / 用户怎么办 / 能否补件）请参阅[KYC 认证错误码](./kyc-reject-codes)。

### 统一响应结构

所有 `/open-api/` 接口返回统一结构，本接口业务数据置于 `data`：

| 字段              | 类型             | 说明                                                                                        |
| --------------- | -------------- | ----------------------------------------------------------------------------------------- |
| `code`          | string         | 系统级返回码，成功为 `SYS_SUCCESS`                                                                  |
| `message`       | string \| null | 成功时通常为 `null`，个别接口返回 `success` 文案；请以 `code` 判断成败，错误时返回对应错误信息                              |
| `messageDetail` | object \| null | 面向终端用户的展示信息（`title`/`message`/`type`/`icon`/`action`/`linkTitle`/`linkUrl`）；成功时通常为 `null` |
| `data`          | object         | 业务数据，见上方字段表                                                                               |

> **请注意**：本接口存在两层语义，集成时请分别判断——以系统级 `code` 是否为 `SYS_SUCCESS` 判断请求是否被系统成功受理，以 `data.status` 判断 KYC 业务结果。`code=SYS_SUCCESS` 仅代表「请求被系统成功受理并返回了工单快照」，**并不代表 KYC 通过**（例如 `status=REJECTED` 时 `code` 仍为 `SYS_SUCCESS`）。`messageDetail` 在失败时用于面向终端用户的展示。

错误码归类、是否可重试与处置建议，请参阅[KYC 认证错误码](./kyc-reject-codes)。

## 下一步

确认 KYC 状态为 `PASSED` 后，即可为该用户[申请虚拟卡 / 开卡](../cards/card-issuing)；若状态为 `NEED_VERIFY`，请先用 [H5 人脸引导页](./h5-kyc-guidance)引导用户完成认证。