> ## 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 信息迁移 > 让已在 DeCard 托管模式完成 KYC 的用户，在合作伙伴自管模式申请卡片时复用已有资料（kycApplyMode=H5-MIGRATION / 引导页 type=9）。本页包含完整的请求字段、工单状态和错误码。 ## 📄 正文 如果您的用户此前已在 **DeCard 托管模式**下完成过 KYC，现在要在**合作伙伴自管模式**下为他发卡，不必让他把证件、人脸、地址再交一遍——可以发起一次 **KYC 信息迁移**，让用户在 DCS 托管的 H5 页面上确认复用已有资料即可。DCS 作为持牌发卡机构，会校验源用户的 KYC 是否满足复用条件，并在通过后把可用的 KYC 信息落到目标用户名下。 迁移复用 H5 KYC 的两步流程，区别只在于申请方式为 `H5-MIGRATION`、引导页类型为 `type=9`，且需额外指明源用户。 ## 什么时候用它 | 您的情况 | 该走 | | --------------------------------- | ------------------------------- | | 用户是全新用户，接入机构自己采集证件后 API 提交 | [申请 KYC（API 模式）](./apply-kyc) | | 用户是全新用户，让他在 DCS 托管页自助填 | [H5 KYC 引导页](./h5-kyc-guidance) | | 用户的证件 / KYC 资料到期，需重新认证 | [更新 KYC 资料](./kyc-renewal) | | **用户已在 DeCard 托管模式完成过 KYC，想直接复用** | **本页** | ## 谁做什么 | 环节 | 谁做 | 说明 | | --------------------------------------------- | ---- | ----------------- | | 判断该用户在 DeCard 托管模式已有 KYC，取到其 `externalUserId` | 接入机构 | 迁移的输入 | | 申请迁移工单、换 H5 链接、把链接发给用户 | 接入机构 | 两次接口调用 | | 校验源用户 KYC 是否满足复用条件 | DCS | 不满足直接拒绝建单 | | 提供 H5 页面供用户确认复用 | DCS | 接入机构无需自建界面 | | 异步推进工单状态并发 Webhook | DCS | 事件类型 `KYC_TICKET` | ## 交互流程 迁移可能被拒。被拒后该工单进入终态，需**重新申请一条新的迁移工单**引导用户重试，不能复用已终态的工单。 KYC 迁移交互流程 KYC 迁移交互流程 ## 步骤一：申请迁移工单（接入机构做） **`POST /open-api/kyc-ticket/v1/apply-kyc-h5`** | 字段 | 类型 | 必填 | 约束 | 说明 | | ------------------ | ------ | -- | --- | -------------------------------------------------------------------------------------------- | | `kycTicketRef` | string | 是 | ≤50 | 接入机构侧业务幂等号，自定义，后续可凭此查询 | | `customerId` | string | 是 | ≤50 | **目标用户**，即本模式下要为其发卡的 `customerId` | | `kycApplyMode` | string | 是 | ≤20 | 固定 `H5-MIGRATION` | | `sourceCustomerId` | string | 是 | ≤50 | **源用户标识**，填该用户在 DeCard 托管模式下的 `externalUserId`。注意字段名虽为 `...CustomerId`，取值不是本模式的 `customerId` | ```json theme={null} { "kycTicketRef": "kyc-mig-20260728-0001", "customerId": "1000000123", "kycApplyMode": "H5-MIGRATION", "sourceCustomerId": "usr_8f3a..." } ``` 响应在统一结构 `data` 中返回新建的工单，`status` 为 `INIT`： ```json theme={null} { "code": "SYS_SUCCESS", "message": "success", "messageDetail": null, "data": { "kycTicketId": "9000000888", "kycTicketRef": "kyc-mig-20260728-0001", "customerId": "1000000123", "status": "INIT", "createTime": "2026-07-28T10:00:00+08:00" } } ``` 本步会**同步校验源用户是否满足复用条件**：不满足时不会建单，直接返回 `DAPI_KYC_MIGRATION_NOT_ELIGIBLE`（见下方错误码）。也就是说拿到 `kycTicketId` 就说明源用户已通过预检，剩下的是用户在 H5 上确认。 ## 步骤二：换取迁移引导页链接（接入机构做） **`POST /open-api/card-redirect/v1/guidance-link`** | 字段 | 类型 | 必填 | 约束 | 说明 | | ----------------------- | ------ | ----- | ---- | ---------------------------------------------------------- | | `type` | string | 是 | ≤1 | 固定 `9`（KYC 信息迁移） | | `customerId` | string | 是 | ≤50 | 同步骤一的目标用户 | | `kycTicketId` | string | 是 | ≤50 | 步骤一返回的 `kycTicketId` | | `errorRedirectUrl` | string | **是** | ≤200 | 迁移失败时跳回的错误页。`type=9` 下**必填**，缺失返回 `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=9` **不需要** `profileId`（仅 `type=7` 申请 KYC-H5 时必填）。 ```json theme={null} { "type": "9", "customerId": "1000000123", "kycTicketId": "9000000888", "errorRedirectUrl": "https://your.app/kyc/failed", "language": "en", "theme": "default", "mode": "light", "userAgent": "Mozilla/5.0 ..." } ``` 响应 `data` 为字符串，即可发给用户的 H5 URL： ```json theme={null} { "code": "SYS_SUCCESS", "message": "success", "messageDetail": null, "data": "https://h5.thedecard-sandbox.com/kyc?token=..." } ``` > H5 链接有时效性。链接过期且工单仍为 `INIT` 时，可重新调用本接口换取新链接，**不需要**重新申请工单。 ## 步骤三：接收结果并按需重试 通过 [`KYC_TICKET` Webhook](../webhooks/events-and-schema) 或主动调 `GET /open-api/kyc-ticket/v1/detail`（传 `kycTicketId` 或 `kycTicketRef`）获知结果： * **`PASSED`**：迁移完成，目标用户已拥有可用 KYC，可继续[开卡](../cards/card-issuing)（`cardApplyMode=NORMAL`，提交该 `kycTicketId` 与 `customerId`）。 * **`REJECTED`**：本次迁移被拒，`errorCode` / `errorMessage` 说明原因。回到步骤一，用**新的 `kycTicketRef`** 申请一条新工单重试。 ### 工单状态（迁移模式） 迁移模式下工单只会出现以下三种状态——**不会**出现 `NEED_VERIFY` 或 `PENDING`： | 状态 | 含义 | 是否终态 | 接入机构下一步 | | ---------- | -------------------------------- | :--: | ----------------------------------------------------- | | `INIT` | 工单已创建，等待用户在 H5 确认；处理中也停留在 `INIT` | 否 | 把 H5 链接发给用户；链接过期可重新调 `guidance-link` | | `PASSED` | 迁移通过，目标用户已拥有可用 KYC | 是 | 无需操作，可进入开卡 | | `REJECTED` | 迁移被拒 | 是 | 读 `errorCode` / `errorMessage`，用新 `kycTicketRef` 重新申请 | ## 错误码 ### apply-kyc-h5（`kycApplyMode=H5-MIGRATION`） 除 [H5 KYC 引导页](./h5-kyc-guidance#apply-kyc-h5-错误码)列出的通用错误码外，迁移模式还可能返回： | 错误码 | 含义 | 触发场景 | 可否重试 | | ------------------------------------ | --------------------------------------------------------------- | ----------------------------------------- | :-----------: | | `DAPI_KYC_SOURCE_USER_NOT_FOUND` | source user not found | 未传 `sourceCustomerId`，或源用户不存在 | ✅ 核对源用户标识后重试 | | `DAPI_KYC_TICKET_CUSTOMER_NOT_FOUND` | kyc ticket customer not found | 目标用户 `customerId` 不存在或未完成注册 | ✅ 先创建用户 | | `DAPI_KYC_MIGRATION_ALREADY_EXISTS` | migration KYC ticket already exists for this source or customer | 该源用户已有进行中 / 已通过的迁移，或目标用户已有可用 KYC | ❌ 无需再迁 | | `DAPI_KYC_MIGRATION_NOT_ELIGIBLE` | not eligible for KYC migration | 源用户 KYC 不满足复用条件（如未通过、与目标用户信息不一致、该渠道未开通迁移） | ❌ 改走常规 KYC 流程 | | `DAPI_POA_COUNTRY_INVALID` | proof of address country not supported | 源用户的地址证明国家不在支持范围 | ❌ 改走常规 KYC 流程 | | `DAPI_TICKET_APPLY_LIMIT_EXCEEDED` | Ticket application exceeds the limit | 同一用户申请过于频繁，触发进件频控 | ✅ 退避后重试 | ### guidance-link（`type=9`） | 错误码 | 含义 | 触发场景 | | ---------------------------------- | --------------------------- | ------------------------------------- | | `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，见[前置准备](../../getting-started/first-steps)。 * 已在本模式下[创建目标用户](../users/create-customer)并拿到 `customerId`。 * 源用户已在 DeCard 托管模式完成 KYC，且您能取到其 `externalUserId`。 * 该渠道已由 DCS 开通迁移能力（未开通时返回 `DAPI_KYC_MIGRATION_NOT_ELIGIBLE`，请联系 DCS 团队）。 ## 下一步 * 迁移通过后为该用户发卡 → [开卡流程](../cards/card-issuing) * 用户资料到期需重新认证 → [更新 KYC 资料](./kyc-renewal) * 查询工单当前状态 → [查询 KYC](./query-kyc)