查询 KYC - DCS Technical Documentation

📄 正文

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

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

前置条件

您已持有企业（Enterprise）的 ApiKey / SecretKey。若尚未领取，请参阅前置准备。
您已提交过 KYC 申请。若还未申请，请先完成申请 KYC。

步骤

准备 KYC 工单标识：使用申请 KYC 时返回的 kycTicketId，或您在申请时传入的幂等键 kycTicketRef（接入机构）。
按鉴权约定生成请求头，调用查询接口（接入机构 → DCS）。
从响应 data.status 读取当前状态并按下表处置（接入机构）：
- NEED_VERIFY：引导用户完成人脸认证，参阅 H5 人脸引导页；
- 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）的生成方式见鉴权。

响应示例

{
  "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：

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

上述 errorCode 为示意值，完整取值与含义请参阅KYC 认证错误码。

`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 资料）/ `H5-MIGRATION`（KYC 信息迁移）
`errorCode`	string	拒绝原因错误码，仅 `REJECTED` 状态返回
`errorMessage`	string	拒绝原因描述，仅 `REJECTED` 状态返回

KYC 工单状态机

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

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

统一响应结构

所有 /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 状态为 PASSED 后，即可为该用户申请虚拟卡 / 开卡；若状态为 NEED_VERIFY，请先用 H5 人脸引导页引导用户完成认证。

​📄 正文

​前置条件

​步骤

​查询 KYC 详情

​查询参数

​请求示例

​响应示例

​data 字段

​KYC 工单状态机

​统一响应结构

​下一步