> ## 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. # H5 KYC 引导页 > 介绍如何让用户在 DCS 托管的 H5 页面上自行完成 KYC，接入机构无需采集证件或处理生物识别数据。完整流程包括创建用户、申请 H5 KYC 工单和获取引导页链接；每一步都标明执行方并提供最小请求与响应示例。 > `guidance-link` 使用 `type=7` 时必须同时传入 `profileId`。当前 `type` 还包含 `4=申请 KYC-活体`、`8=更新 KYC 资料`；H5 模式通常不会出现 `REJECTED`，但接入机构仍应兼容该状态。 ## 📄 正文 无论您是想完全托管 KYC 体验、还是不愿在自己后端处理任何证件与人脸数据，都可以用 H5 KYC 引导页：把用户引导到 DCS 托管的 H5 页面，让他们自助完成国籍选择、证件上传、人脸采集与地址填写。DCS 是持牌发卡机构，KYC 全流程在我们这一侧完成核验与安全存储，接入机构只负责把链接发给用户、并接收结果。 H5 模式与 [API 模式申请 KYC](../kyc/apply-kyc) 二选一： | 您希望 | 适合用 | | ----------------------------- | ---------------------------------- | | 接入机构自己采集证件/地址信息，再通过 API 一次性提交 | [申请 KYC（API 模式）](../kyc/apply-kyc) | | 接入机构不接管采集，让用户在 DCS 的 H5 上自己填 | 本页（H5 模式） | *** ### DCS 与接入机构的分工 H5 模式下，接入机构只做三件事，其余都由 DCS 承担。 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`。详见 [创建用户](../users/create-customer)。 *** ### 步骤二：申请 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 资料](./kyc-renewal)；复用用户在 DeCard 托管模式已有的 KYC 见 [KYC 信息迁移](./kyc-migration)。 **最小请求** ```json theme={null} { "kycTicketRef": "kyc-20260617-0001", "customerId": "1000000123" } ``` **响应（`APIApplyKycH5Response`，已剥去统一响应结构）** | 字段 | 类型 | 说明 | | ---------------------------- | ------ | ------------------ | | `kycTicketId` | string | KYC 工单 ID，步骤三与查询使用 | | `kycTicketRef` | string | 回显的幂等号 | | `customerId` | string | 用户 ID | | `status` | string | 工单状态，新建为 `INIT` | | `createTime` | string | 创建时间 | | `errorCode` / `errorMessage` | string | 失败时返回 | ```json theme={null} { "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`）。字段含义见 [授权拒绝与错误码](../transactions/decline-codes)。 **幂等行为** * 同 `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 资料」。请按本页枚举值传参。 **最小请求** ```json theme={null} { "type": "7", "customerId": "1000000123", "kycTicketId": "9000000888", "profileId": "<联系 DCS 获取>", "language": "en", "theme": "default", "mode": "light", "userAgent": "Mozilla/5.0 ..." } ``` **响应** 接口在统一结构的 `data` 字段返回 H5 URL（`data` 为字符串）。接入机构把该 URL 发给用户即可。 ```json theme={null} { "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 数据结构](../webhooks/events-and-schema)。 **主动查询**（接入机构做）：任意时刻调 `GET /open-api/kyc-ticket/v1/detail`，传 `kycTicketId` 或 `kycTicketRef` 查询当前状态。 *** ### KYC 工单状态（H5 模式） | 状态 | 描述 | 是否终态 | 后续操作 | | --------- | ----------------- | ---- | ------------------------------------ | | `INIT` | 工单已创建，等待用户在 H5 提交 | 否 | 把 H5 链接发给用户；过期重新调 `guidance-link` 续期 | | `PENDING` | 用户已提交，DCS 异步审核中 | 否 | 等 Webhook 或主动轮询 | | `PASSED` | 审核通过 | 是 | 进入 [虚拟卡申请](../cards/virtual-card) | > * 常规 `H5` 模式正常仅出现 `INIT` / `PENDING` / `PASSED`；审核异常通常维持 `PENDING` 等待人工介入。 > * `H5-RENEWAL` 续期流程的状态为 `RENEWAL_INIT / PENDING / RETRY / PASS / REJECT`，并映射回工单 `INIT / PASSED / REJECTED`；`H5-MIGRATION` 的状态取值见 [KYC 信息迁移](./kyc-migration)。 > * 同一 `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 拒绝码](./kyc-reject-codes)；通用和授权错误码见 [授权拒绝与错误码](../transactions/decline-codes)。 *** ### 前置条件 * 已拥有企业（Enterprise）的 ApiKey / SecretKey，见 [入驻指南](../../getting-started/first-steps)。 * 已创建用户（步骤一），见 [创建用户](../users/create-customer)。 * 已从 DCS 团队拿到 `profileId`（卡配置 ID）。 *** ## 下一步 * KYC 通过（`status=PASSED`）后，前往 [申请虚拟卡](../cards/virtual-card)，以 `cardApplyMode=NORMAL` 提交 `kycTicketId` 与 `customerId` 完成开卡；同一用户后续再开卡可继续复用同一个 `kycTicketId`。 * 偏好走 API 提交证件而非托管页？见 [申请 KYC](./apply-kyc)。 * 随时查询工单当前状态，见 [查询 KYC](./query-kyc)。