KYC 信息迁移 - DCS Technical Documentation

📄 正文

如果您的用户此前已在 DeCard 托管模式下完成过 KYC，现在要在合作伙伴自管模式下为他发卡，不必让他把证件、人脸、地址再交一遍——可以发起一次 KYC 信息迁移，让用户在 DCS 托管的 H5 页面上确认复用已有资料即可。DCS 作为持牌发卡机构，会校验源用户的 KYC 是否满足复用条件，并在通过后把可用的 KYC 信息落到目标用户名下。迁移复用 H5 KYC 的两步流程，区别只在于申请方式为 H5-MIGRATION、引导页类型为 type=9，且需额外指明源用户。

什么时候用它

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

谁做什么

环节	谁做	说明
判断该用户在 DeCard 托管模式已有 KYC，取到其 `externalUserId`	接入机构	迁移的输入
申请迁移工单、换 H5 链接、把链接发给用户	接入机构	两次接口调用
校验源用户 KYC 是否满足复用条件	DCS	不满足直接拒绝建单
提供 H5 页面供用户确认复用	DCS	接入机构无需自建界面
异步推进工单状态并发 Webhook	DCS	事件类型 `KYC_TICKET`

交互流程

迁移可能被拒。被拒后该工单进入终态，需重新申请一条新的迁移工单引导用户重试，不能复用已终态的工单。

步骤一：申请迁移工单（接入机构做）

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`

{
  "kycTicketRef": "kyc-mig-20260728-0001",
  "customerId": "1000000123",
  "kycApplyMode": "H5-MIGRATION",
  "sourceCustomerId": "usr_8f3a..."
}

响应在统一结构 data 中返回新建的工单，status 为 INIT：

{
  "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 时必填）。

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

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

H5 链接有时效性。链接过期且工单仍为 INIT 时，可重新调用本接口换取新链接，不需要重新申请工单。

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

通过 KYC_TICKET Webhook 或主动调 GET /open-api/kyc-ticket/v1/detail（传 kycTicketId 或 kycTicketRef）获知结果：

PASSED：迁移完成，目标用户已拥有可用 KYC，可继续开卡（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 引导页列出的通用错误码外，迁移模式还可能返回：

错误码	含义	触发场景	可否重试
`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，见前置准备。
已在本模式下创建目标用户并拿到 customerId。
源用户已在 DeCard 托管模式完成 KYC，且您能取到其 externalUserId。
该渠道已由 DCS 开通迁移能力（未开通时返回 DAPI_KYC_MIGRATION_NOT_ELIGIBLE，请联系 DCS 团队）。

下一步

迁移通过后为该用户发卡 → 开卡流程
用户资料到期需重新认证 → 更新 KYC 资料
查询工单当前状态 → 查询 KYC

​📄 正文

​什么时候用它

​谁做什么

​交互流程

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

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

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

​工单状态（迁移模式）

​错误码

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

​guidance-link（type=9）

​前置条件

​下一步

📄 正文

什么时候用它

谁做什么

交互流程

步骤一：申请迁移工单（接入机构做）

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

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

工单状态（迁移模式）

错误码

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

guidance-link（`type=9`）

前置条件

下一步