H5 KYC 引导页 - DCS Technical Documentation

guidance-link 使用 type=7 时必须同时传入 profileId。当前 type 还包含 4=申请 KYC-活体、8=更新 KYC 资料；H5 模式通常不会出现 REJECTED，但接入机构仍应兼容该状态。

📄 正文

无论您是想完全托管 KYC 体验、还是不愿在自己后端处理任何证件与人脸数据，都可以用 H5 KYC 引导页：把用户引导到 DCS 托管的 H5 页面，让他们自助完成国籍选择、证件上传、人脸采集与地址填写。DCS 是持牌发卡机构，KYC 全流程在我们这一侧完成核验与安全存储，接入机构只负责把链接发给用户、并接收结果。 H5 模式与 API 模式申请 KYC 二选一：

您希望	适合用
接入机构自己采集证件/地址信息，再通过 API 一次性提交	申请 KYC（API 模式）
接入机构不接管采集，让用户在 DCS 的 H5 上自己填	本页（H5 模式）

DCS 与接入机构的分工

H5 模式下，接入机构只做三件事，其余都由 DCS 承担。

环节	谁做	说明
提供 H5 页面（证件类型选择、Sumsub SDK 上传/人脸、职业/收入、地址）	DCS	接入机构无需自建任何 KYC UI
接收并安全存储用户提交的 KYC 信息	DCS
提交至 DCS 风控与 Sumsub 做身份核验，并异步推进工单状态	DCS
状态变化时发 Webhook 通知	DCS	事件类型 `KYC_TICKET`
把 H5 URL 发给用户、接收结果、推进开卡	接入机构

步骤一：创建用户（接入机构做）

调用 POST /open-api/customer/v1/create-customer 创建用户，拿到 customerId。详见创建用户。

步骤二：申请 H5 KYC 工单（接入机构做）

调用 POST /open-api/kyc-ticket/v1/apply-kyc-h5 申请工单。 请求体（APIApplyKycH5Request）

字段	类型	必填	约束	说明
`kycTicketRef`	string	是	≤50	接入机构侧业务幂等号，自定义（推荐用业务单号），后续可凭此查询
`customerId`	string	是	≤50	步骤一返回的用户 ID
`kycApplyMode`	string	否	≤20	申请方式：`H5`（初次 KYC，默认）/ `H5-RENEWAL`（更新 KYC 资料）/ `H5-MIGRATION`（KYC 信息迁移）。不传按 `H5` 处理
`sourceCustomerId`	string	`H5-MIGRATION` 时必填	≤50	源用户标识，填该用户在 DeCard 托管模式下的 `externalUserId`（注意字段名虽为 `...CustomerId`，取值不是本模式的 `customerId`）

注：kycApplyMode 字段以接口定义为准。需要让老用户重新提交/更新资料时传 H5-RENEWAL。本页只讲初次 KYC（H5）。资料到期需重新认证见更新 KYC 资料；复用用户在 DeCard 托管模式已有的 KYC 见 KYC 信息迁移。

最小请求

{
  "kycTicketRef": "kyc-20260617-0001",
  "customerId": "1000000123"
}

响应（APIApplyKycH5Response，已剥去统一响应结构）

字段	类型	说明
`kycTicketId`	string	KYC 工单 ID，步骤三与查询使用
`kycTicketRef`	string	回显的幂等号
`customerId`	string	用户 ID
`status`	string	工单状态，新建为 `INIT`
`createTime`	string	创建时间
`errorCode` / `errorMessage`	string	失败时返回

{
  "code": "SYS_SUCCESS",
  "message": "success",
  "messageDetail": null,
  "data": {
    "kycTicketId": "9000000888",
    "kycTicketRef": "kyc-20260617-0001",
    "customerId": "1000000123",
    "status": "INIT",
    "createTime": "2026-06-17T08:00:00+08:00"
  }
}

统一响应结构为 {code, message, messageDetail, data}：code 为业务状态码（成功为 SYS_SUCCESS），messageDetail 为附加错误明细（成功时为 null）。字段含义见授权拒绝与错误码。

幂等行为

同 kycTicketRef 不存在 → 创建新 INIT 工单。
同 kycTicketRef 已存在、归属同一 enterprise/customer、状态 = INIT → 幂等返回已有工单（重试场景）。
其他情况（归属不一致 / 已 PENDING / 已 PASSED）→ 抛错，见下方错误码表。

步骤三：换 H5 链接（接入机构做）

调用 POST /open-api/card-redirect/v1/guidance-link，设置 type=7，把工单换成可发给用户的 H5 URL。 请求体（H5 KYC 相关字段，APIGuidanceRequest）

字段	类型	必填	约束	说明
`type`	string	是	≤1	固定 `7`（申请 KYC-H5）。完整枚举见下表
`customerId`	string	是	≤50	同步骤一/二
`kycTicketId`	string	type=7 时必填	≤50	步骤二返回的 `kycTicketId`
`profileId`	string	type=7 时必填	≤50	卡配置 ID，联系 DCS 团队获取
`language`	string	是	长度 2	`zh` / `en`；非 zh 国家统一映射为 `en`
`theme`	string	是	≤10	如 `default`（`blue` 仅支持卡信息查询）
`mode`	string	是	≤10	`light` / `dark`
`userAgent`	string	是	≤300	用户浏览器 UA
`successfulRedirectUrl`	string	否	≤200	完成后成功跳转地址
`errorRedirectUrl`	string	否	≤200	失败跳转地址
`submitAutoClosed`	string	否	≤1	`Y` 提交成功后自动关闭页面 / `N` 不关闭
`primaryColor`	string	否	≤7	主色调，如 `#FFFFFF`

type 完整枚举（以接口定义为准）：

type	含义	额外必填
1	卡信息查询	`cardId`
2	设置 PIN	`cardId`、`otpStatus`
3	重置 PIN	`cardId`、`otpStatus`
4	申请 KYC-活体（人脸）	`kycTicketId`
5	信息验证	`cardOrderId`
6	补充开卡信息	`cardOrderId`
7	申请 KYC-H5	`kycTicketId`、`profileId`
8	更新 KYC 资料	`kycTicketId`、`errorRedirectUrl`
9	KYC 信息迁移	`kycTicketId`、`errorRedirectUrl`

type=4 表示「申请 KYC-活体」，type=8 表示「更新 KYC 资料」。请按本页枚举值传参。

最小请求

{
  "type": "7",
  "customerId": "1000000123",
  "kycTicketId": "9000000888",
  "profileId": "<联系 DCS 获取>",
  "language": "en",
  "theme": "default",
  "mode": "light",
  "userAgent": "Mozilla/5.0 ..."
}

响应接口在统一结构的 data 字段返回 H5 URL（data 为字符串）。接入机构把该 URL 发给用户即可。

{
  "code": "SYS_SUCCESS",
  "message": "success",
  "messageDetail": null,
  "data": "https://h5.thedecard-sandbox.com/kyc?token=..."
}

H5 链接有时效性，请在有效期内引导用户完成。链接过期可重新调本接口续期（status 仍为 INIT 时）。

步骤四：接收结果（Webhook + 主动查询）

Webhook（推荐，DCS 主动推）：配置好 Webhook 后，工单状态变化会推送 KYC_TICKET 事件。

时机	事件	status
用户在 H5 完成最终提交	KYC_TICKET	`PENDING`
异步审核通过	KYC_TICKET	`PASSED`

Webhook 数据结构见 Webhook 数据结构。 主动查询（接入机构做）：任意时刻调 GET /open-api/kyc-ticket/v1/detail，传 kycTicketId 或 kycTicketRef 查询当前状态。

KYC 工单状态（H5 模式）

状态	描述	是否终态	后续操作
`INIT`	工单已创建，等待用户在 H5 提交	否	把 H5 链接发给用户；过期重新调 `guidance-link` 续期
`PENDING`	用户已提交，DCS 异步审核中	否	等 Webhook 或主动轮询
`PASSED`	审核通过	是	进入虚拟卡申请

常规 H5 模式正常仅出现 INIT / PENDING / PASSED；审核异常通常维持 PENDING 等待人工介入。

H5-RENEWAL 续期流程的状态为 RENEWAL_INIT / PENDING / RETRY / PASS / REJECT，并映射回工单 INIT / PASSED / REJECTED；H5-MIGRATION 的状态取值见 KYC 信息迁移。

同一 kycTicketRef 重新生成链接要求工单处于 INIT：NEED_VERIFY/PENDING 返回处理中，PASSED 返回已通过，REJECTED 返回验证失败。

apply-kyc-h5 错误码

错误码	描述
`DAPI_KYC_TICKET_CUSTOMER_NOT_FOUND`	KYC 工单对应用户不存在
`DAPI_KYC_TICKET_CUSTOMER_NOT_FOUND_IN_ENTERPRISE`	该用户不属于当前企业
`DAPI_KYC_TICKET_REF_NOT_UNIQUE`	`kycTicketRef` 不唯一（与已有不同归属的工单冲突）
`DAPI_KYC_TICKET_IS_IN_PROCESSING`	工单处理中（已 `PENDING`）
`DAPI_KYC_TICKET_ALREADY_PASSED`	工单已通过，请直接申请虚拟卡

apply-kyc-h5 相关错误码分类见 KYC 拒绝码；通用和授权错误码见授权拒绝与错误码。

前置条件

已拥有企业（Enterprise）的 ApiKey / SecretKey，见入驻指南。
已创建用户（步骤一），见创建用户。
已从 DCS 团队拿到 profileId（卡配置 ID）。

下一步

KYC 通过（status=PASSED）后，前往申请虚拟卡，以 cardApplyMode=NORMAL 提交 kycTicketId 与 customerId 完成开卡；同一用户后续再开卡可继续复用同一个 kycTicketId。
偏好走 API 提交证件而非托管页？见申请 KYC。
随时查询工单当前状态，见查询 KYC。

​📄 正文

​DCS 与接入机构的分工

​步骤一：创建用户（接入机构做）

​步骤二：申请 H5 KYC 工单（接入机构做）

​步骤三：换 H5 链接（接入机构做）

​步骤四：接收结果（Webhook + 主动查询）

​KYC 工单状态（H5 模式）

​apply-kyc-h5 错误码

​前置条件

​下一步