KYC information migration

📄 Guide

If your user already completed KYC under the DeCard-Managed model and you now want to issue them a card under the Partner-Managed model, they do not have to submit their documents, selfie and address all over again — you can start a KYC information migration and let the user simply confirm the reuse of their existing data on a DCS-hosted H5 page. As a licensed card issuer, DCS verifies whether the source user’s KYC is eligible for reuse and, once it passes, attaches usable KYC information to the target user. Migration reuses the same two-step H5 KYC flow; the only differences are that the application mode is H5-MIGRATION, the guide page type is type=9, and the source user must be identified.

When to use it

Your situation	Use
Brand-new user, you collect the documents and submit them via API	Apply for KYC (API mode)
Brand-new user, let them fill everything in on the DCS-hosted page	H5 KYC guide page
The user’s documents / KYC data have expired and need re-verification	Updating KYC information
The user already completed KYC under the DeCard-Managed model and you want to reuse it	This page

Who does what

Step	Who	Notes
Determine that the user already has KYC under the DeCard-Managed model and obtain their `externalUserId`	You	The input to a migration
Apply for the migration ticket, exchange it for an H5 link, send the link to the user	You	Two API calls
Verify whether the source user’s KYC is eligible for reuse	DCS	Not eligible means the ticket is rejected up front
Provide the H5 page on which the user confirms the reuse	DCS	No UI to build on your side
Advance the ticket status asynchronously and send webhooks	DCS	Event type `KYC_TICKET`

Interaction flow

A migration can be rejected. Once rejected the ticket is in a terminal state, so you must apply for a brand-new migration ticket to let the user retry — a terminal ticket cannot be reused.

Step 1: Apply for the migration ticket (you)

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

Field	Type	Required	Constraints	Description
`kycTicketRef`	string	Yes	≤50	Your own business idempotency key; you can query by it later
`customerId`	string	Yes	≤50	The target user — the `customerId` in this model you want to issue a card to
`kycApplyMode`	string	Yes	≤20	Fixed `H5-MIGRATION`
`sourceCustomerId`	string	Yes	≤50	The source user identifier — pass that user’s `externalUserId` from the DeCard-Managed model. Note that despite the `...CustomerId` name this is not a `customerId` of this model

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

The response returns the new ticket inside the common envelope’s data, with status set to 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"
  }
}

This step synchronously checks whether the source user is eligible for reuse. If not, no ticket is created and DAPI_KYC_MIGRATION_NOT_ELIGIBLE is returned (see the error codes below). In other words, once you have a kycTicketId the source user has already passed the pre-check and all that remains is the user’s confirmation on H5.

Step 2: Exchange for the migration guide link (you)

POST /open-api/card-redirect/v1/guidance-link

Field	Type	Required	Constraints	Description
`type`	string	Yes	≤1	Fixed `9` (KYC information migration)
`customerId`	string	Yes	≤50	The same target user as in step 1
`kycTicketId`	string	Yes	≤50	The `kycTicketId` returned in step 1
`errorRedirectUrl`	string	Yes	≤200	Error page to redirect to when the migration fails. Required for `type=9`; omitting it returns `DAPI_SYS_ILLEGAL_PARAM`
`language`	string	Yes	Length 2	`zh` / `en`; non-zh countries are uniformly mapped to `en`
`theme`	string	Yes	≤10	Such as `default`
`mode`	string	Yes	≤10	`light` / `dark`
`userAgent`	string	Yes	≤300	User browser UA
`successfulRedirectUrl`	string	No	≤200	Redirect address on success
`submitAutoClosed`	string	No	≤1	`Y` closes the page automatically after a successful submission / `N` does not
`primaryColor`	string	No	≤7	Main colour, such as `#FFFFFF`

type=9 does not need profileId (that is required only for type=7, apply for KYC-H5).

{
  "type": "9",
  "customerId": "1000000123",
  "kycTicketId": "9000000888",
  "errorRedirectUrl": "https://your.app/kyc/failed",
  "language": "en",
  "theme": "default",
  "mode": "light",
  "userAgent": "Mozilla/5.0 ..."
}

The response data is a string — the H5 URL you hand to the user:

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

The H5 link has a limited lifetime. If it expires while the ticket is still INIT, call this endpoint again for a fresh link — you do not need to apply for a new ticket.

Step 3: Receive the result and retry if needed

Learn the outcome from the KYC_TICKET webhook or by calling GET /open-api/kyc-ticket/v1/detail yourself (with kycTicketId or kycTicketRef):

PASSED: the migration is complete, the target user now has usable KYC, and you can go on to issue a card (cardApplyMode=NORMAL, submitting that kycTicketId and customerId).
REJECTED: this migration was rejected; errorCode / errorMessage explain why. Go back to step 1 and apply for a new ticket with a new kycTicketRef.

Ticket status (migration mode)

In migration mode a ticket only ever takes these three statuses — NEED_VERIFY and PENDING do not occur:

Status	Meaning	Terminal	Your next step
`INIT`	Ticket created, waiting for the user to confirm on H5; processing also stays at `INIT`	No	Send the H5 link to the user; call `guidance-link` again if the link expires
`PASSED`	Migration passed, the target user now has usable KYC	Yes	Nothing to do; proceed to card issuance
`REJECTED`	Migration rejected	Yes	Read `errorCode` / `errorMessage` and re-apply with a new `kycTicketRef`

Error codes

apply-kyc-h5 (`kycApplyMode=H5-MIGRATION`)

In addition to the common error codes listed on the H5 KYC guide page, migration mode can also return:

Error code	Meaning	Trigger	Retryable
`DAPI_KYC_SOURCE_USER_NOT_FOUND`	source user not found	`sourceCustomerId` not supplied, or the source user does not exist	✅ Verify the source identifier and retry
`DAPI_KYC_TICKET_CUSTOMER_NOT_FOUND`	kyc ticket customer not found	The target `customerId` does not exist or registration is incomplete	✅ Create the user first
`DAPI_KYC_MIGRATION_ALREADY_EXISTS`	migration KYC ticket already exists for this source or customer	The source user already has an in-progress or passed migration, or the target user already has usable KYC	❌ No migration needed
`DAPI_KYC_MIGRATION_NOT_ELIGIBLE`	not eligible for KYC migration	The source user’s KYC is not eligible for reuse (not passed, inconsistent with the target user’s details, or migration not enabled for this channel)	❌ Use the regular KYC flow
`DAPI_POA_COUNTRY_INVALID`	proof of address country not supported	The source user’s proof-of-address country is out of scope	❌ Use the regular KYC flow
`DAPI_TICKET_APPLY_LIMIT_EXCEEDED`	Ticket application exceeds the limit	Too many applications for the same user; the intake rate limit was hit	✅ Back off and retry

guidance-link (`type=9`)

Error code	Meaning	Trigger
`DAPI_SYS_ILLEGAL_PARAM`	System illegal param	`kycTicketId` or `errorRedirectUrl` is empty
`DAPI_KYC_TICKET_NOT_FOUND`	kyc ticket not found	Ticket does not exist / belongs to someone else / is not a migration ticket
`DAPI_KYC_TICKET_IS_IN_PROCESSING`	KYC ticket is in processing	The ticket has already been submitted and is still being processed; the operation cannot be repeated
`DAPI_KYC_TICKET_ALREADY_PASSED`	KYC ticket already passed	The ticket already passed — go straight to card issuance

Prerequisites

You hold the Enterprise ApiKey / SecretKey — see First steps.
You have created the target user in this model and hold their customerId.
The source user has completed KYC under the DeCard-Managed model and you can obtain their externalUserId.
DCS has enabled migration for your channel (otherwise DAPI_KYC_MIGRATION_NOT_ELIGIBLE is returned — contact the DCS team).

Next steps

Issue a card for the user after a successful migration → Card issuance
The user’s data has expired and needs re-verification → Updating KYC information
Check the current ticket status → Query KYC

Getting Started

Basic Concepts

How to Use

Integration Resources

Customer Success

📄 Guide

When to use it

Who does what

Interaction flow

Step 1: Apply for the migration ticket (you)

Step 2: Exchange for the migration guide link (you)

Step 3: Receive the result and retry if needed

Ticket status (migration mode)

Error codes

apply-kyc-h5 (`kycApplyMode=H5-MIGRATION`)

guidance-link (`type=9`)

Prerequisites

Next steps

​📄 Guide

​When to use it

​Who does what

​Interaction flow

​Step 1: Apply for the migration ticket (you)

​Step 2: Exchange for the migration guide link (you)

​Step 3: Receive the result and retry if needed

​Ticket status (migration mode)

​Error codes

​apply-kyc-h5 (kycApplyMode=H5-MIGRATION)

​guidance-link (type=9)

​Prerequisites

​Next steps

📄 Guide

When to use it

Who does what

Interaction flow

Step 1: Apply for the migration ticket (you)

Step 2: Exchange for the migration guide link (you)

Step 3: Receive the result and retry if needed

Ticket status (migration mode)

Error codes

apply-kyc-h5 (`kycApplyMode=H5-MIGRATION`)

guidance-link (`type=9`)

Prerequisites

Next steps