更新 KYC 资料 - DCS Technical Documentation

📄 正文

证件与 KYC 资料都有有效期。到期后用户需要重新完成一次认证，账户才能维持合规、继续正常消费。DCS 会在检测到到期时主动通知您，您只需引导用户在 DCS 托管的 H5 页面上重新采集证件与人脸即可。更新复用 H5 KYC 的两步流程，区别只在于申请方式为 H5-RENEWAL、引导页类型为 type=8。

什么时候用它

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

调用查询用户 KYC 信息返回 kycRenewalRequired=true；
收到用户级 KYC Webhook，其中 kycRenewalRequired=true。

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

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

与其他 KYC 路径的关系

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

交互流程

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

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

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

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

{
  "kycTicketRef": "kyc-renew-20260728-0001",
  "customerId": "1000000123",
  "kycApplyMode": "H5-RENEWAL"
}

本步会同步校验该用户当前确实需要更新。若该用户并不需要更新（kycRenewalRequired 不为 true），不会建单，直接返回 DAPI_KYC_RENEWAL_NOT_REQUIRED。请先通过查询用户 KYC 信息或 Webhook 确认后再调用。

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

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

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 或主动调 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 引导页列出的通用错误码外，更新模式还可能返回：

错误码	含义	触发场景	可否重试
`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，见前置准备。
已确认该用户 kycRenewalRequired=true，见查询用户 KYC 信息。
已配置可接收 KYC 与 KYC_TICKET 事件的 Webhook 地址，见 Webhook 配置。

下一步

查询用户当前是否需要更新 → 查询用户 KYC 信息
复用用户在 DeCard 托管模式已有的 KYC → KYC 信息迁移
Webhook 事件与字段 → 事件与数据结构

​📄 正文

​什么时候用它

​与其他 KYC 路径的关系

​交互流程

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

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

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

​工单状态（更新模式）

​错误码

​apply-kyc-h5（kycApplyMode=H5-RENEWAL）

​guidance-link（type=8）

​前置条件

​下一步

📄 正文

什么时候用它

与其他 KYC 路径的关系

交互流程

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

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

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

工单状态（更新模式）

错误码

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

guidance-link（`type=8`）

前置条件

下一步