Updating KYC information

📄 Guide

Identity documents and KYC data both have an expiry. Once they expire the user must complete verification again for the account to stay compliant and keep spending normally. DCS notifies you proactively when it detects an expiry; all you have to do is guide the user to re-capture their documents and selfie on a DCS-hosted H5 page. Renewal reuses the same two-step H5 KYC flow; the only differences are that the application mode is H5-RENEWAL and the guide page type is type=8.

When to use it

A user needs to renew their KYC data whenever either of these holds:

Query a user’s KYC information returns kycRenewalRequired=true;
You receive the user-level KYC webhook with kycRenewalRequired=true.

The webhook’s kycRenewalType states which factors need renewing (POI proof of identity / SELFIE), which you can use to prompt for only that item in your front end.

Until the renewal completes, some of the user’s operations (such as spending) may be restricted. Guide the user through it as early as possible.

How this relates to the other KYC paths

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 data has expired and needs re-verification	This page
The user already completed KYC under the DeCard-Managed model and you want to reuse it	KYC information migration

Interaction flow

A renewal can be rejected. Once rejected the ticket is terminal, but the user still needs to renew (kycRenewalRequired remains true); apply for a new ticket to let them retry until it passes and kycRenewalRequired becomes false.

Step 1: Apply for the renewal 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 user whose data needs renewing
`kycApplyMode`	string	Yes	≤20	Fixed `H5-RENEWAL`

{
  "kycTicketRef": "kyc-renew-20260728-0001",
  "customerId": "1000000123",
  "kycApplyMode": "H5-RENEWAL"
}

This step synchronously checks that the user really does need to renew. If they do not (kycRenewalRequired is not true), no ticket is created and DAPI_KYC_RENEWAL_NOT_REQUIRED is returned. Confirm first via Query a user’s KYC information or the webhook.

Only one in-progress (INIT) renewal ticket is allowed per user at a time; you can apply again only after the previous one reaches a terminal state (PASSED / REJECTED).

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

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

Field	Type	Required	Constraints	Description
`type`	string	Yes	≤1	Fixed `8` (update KYC information)
`customerId`	string	Yes	≤50	Same as step 1
`kycTicketId`	string	Yes	≤50	The `kycTicketId` returned in step 1
`errorRedirectUrl`	string	Yes	≤200	Error page to redirect to when the renewal fails. Required for `type=8`; 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=8 does not need profileId (that is required only for type=7, apply for KYC-H5).

The response data is a string — the H5 URL you hand to the user. The 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 review outcome from the KYC_TICKET webhook or by calling GET /open-api/kyc-ticket/v1/detail:

PASSED: the renewal is complete. You will then receive the user-level KYC webhook with kycRenewalRequired=false and the restriction is lifted.
REJECTED: this renewal was rejected and kycRenewalRequired is still true. Go back to step 1 and apply for a new ticket with a new kycTicketRef.

Ticket status (renewal mode)

In renewal 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 submit on H5; review also stays at `INIT`	No	Send the H5 link to the user; call `guidance-link` again if the link expires
`PASSED`	Review passed, renewal complete	Yes	Wait for the `KYC` webhook to report `kycRenewalRequired=false`
`REJECTED`	Review rejected	Yes	`kycRenewalRequired` is still `true`; re-apply with a new `kycTicketRef`

Error codes

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

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

Error code	Meaning	Trigger	Retryable
`DAPI_KYC_RENEWAL_NOT_REQUIRED`	customer does not need KYC renewal	This user does not currently need to renew, or their record is incomplete	❌ Confirm `kycRenewalRequired=true` first
`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=8`)

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 renewal 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

Prerequisites

You hold the Enterprise ApiKey / SecretKey — see First steps.
You have confirmed kycRenewalRequired=true for this user — see Query a user’s KYC information.
You have configured a webhook endpoint that can receive KYC and KYC_TICKET events — see Webhook configuration.

Next steps

Check whether a user currently needs to renew → Query a user’s KYC information
Reuse KYC the user already completed under the DeCard-Managed model → KYC information migration
Webhook events and fields → Events and data structures

Getting Started

Basic Concepts

How to Use

Integration Resources

Customer Success

📄 Guide

When to use it

How this relates to the other KYC paths

Interaction flow

Step 1: Apply for the renewal ticket (you)

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

Step 3: Receive the result and retry if needed

Ticket status (renewal mode)

Error codes

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

guidance-link (`type=8`)

Prerequisites

Next steps

​📄 Guide

​When to use it

​How this relates to the other KYC paths

​Interaction flow

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

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

​Step 3: Receive the result and retry if needed

​Ticket status (renewal mode)

​Error codes

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

​guidance-link (type=8)

​Prerequisites

​Next steps

📄 Guide

When to use it

How this relates to the other KYC paths

Interaction flow

Step 1: Apply for the renewal ticket (you)

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

Step 3: Receive the result and retry if needed

Ticket status (renewal mode)

Error codes

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

guidance-link (`type=8`)

Prerequisites

Next steps