Why setting and updating a PIN in the DeCard-Managed model runs through a hosted guidance page rather than a direct API, plus how to obtain the PIN guidance link (action=UPDATE_PIN), the full sequence, and how to handle errors.
Cardholders need a PIN to withdraw cash at an ATM and to pay at some offline POS terminals. As a licensed issuer with its own BINs, DCS treats setting a PIN as a sensitive operation that has to happen inside a trusted page: in the DeCard-Managed model, PINs are not set or updated through a direct API. Instead you send the user to a DCS-hosted H5 guidance page where they set the PIN themselves, so PIN entry and encryption both happen inside the DCS-hosted page and never touch your backend.
Prerequisite: you must already have issued the card and hold its cardId. If you are not yet sure how to apply for a card, read Issuing Cards first.
Mental model: why the PIN goes through a guidance page instead of an API
The DeCard-Managed model groups PIN setting with the operations an end user must complete in person inside a trusted page, alongside KYC, viewing sensitive card details and activating a physical card. All of them run through the same redirect guidance page (guidanceLink):
Your backend calls the guidance page endpoint with the operation type (action / type) and the target card identifier, and receives a single-use guidance link.
You redirect the user to that link.
The user enters and submits the new PIN inside the DCS-hosted H5 page, which validates and encrypts it.
When they are done, the page returns the user to your app at the redirect URL you supplied.
That way neither your client nor your backend ever handles the PIN in plaintext, which keeps your PCI and compliance burden low.
The PIN page reuses the common guidance page endpoint, which identifies the card precisely with cardId.
Endpoint
Card identifier field
Value that triggers the PIN flow
POST /redirect/v2/guidance-link
cardId
action = UPDATE_PIN
The full parameter table and redirect mechanics for the guidance page endpoint are documented in one place, H5 KYC / Card Application Guidance Page. This page lists only the fields that matter for the PIN flow, to avoid duplication.
Target card ID, required for any action that operates on a specific card, UPDATE_PIN included
successRedirectUrl
string
Yes
Redirect URL used after the PIN is set, max length 300
errorRedirectUrl
string
Yes
Redirect URL used if setting the PIN fails, max length 300
referer
string
No
Referrer, used for security checks, max length 300
userAgent
string
No
User agent, used for security checks, max length 300
language
string
No
Language of the customer-facing guidance-link, lowercase hyphenated and case-sensitive: zh / en / ko / ja / zh-Hant / th / vi, max length 10
selectCardPageShow
string
No
Whether to skip the card selection page when the user holds several cards: 0 = do not skip, 1 = skip, max length 1
theme
string
No
Theme, for example blue, max length 10
mode
string
No
Light or dark mode, for example dark / light, max length 10
The required fields are action / externalUserId / successRedirectUrl / errorRedirectUrl / cardId. theme and mode are optional, but sending them every time is recommended, in line with the sibling page Viewing Encrypted Card Details.Four further fields belong to the full guidance page contract but are not used by the PIN flow: nationality (nationality, honoured only by KYC_GUIDE), selectNationalityShow (nationality selection page, honoured only by KYC_GUIDE), primaryColor (primary colour, a hex value starting with #) and applyId (required when uploading extra documents). For the complete field table, see H5 KYC / Card Application Guidance Page.
Authentication: the example omits the authentication headers to keep the focus on the business fields. A real call must carry X-DAPI-API-KEY / X-DAPI-SIGN / X-DAPI-TIMESTAMP / X-DAPI-NONCE (HMAC-SHA256 signature); for the rules, see the Authentication Guide.
Every example value is a placeholder. Never put a real externalUserId, cardId, API key or secret, or any cardholder personal data into a request or a log.
The guidance page endpoint returns the common envelope { code, message, messageDetail, data }. On success code = SYS_SUCCESS and data is the guidance page link, as a string. messageDetail is a message object (its schema has seven sub-fields: message / title / type / icon / action / linkTitle / linkUrl) used to carry structured messaging on failure; on success it is normally null.
On failure, messageDetail may come back in this shape (every sub-field is a string):
{ "message": "...", "title": "...", "type": "...", "icon": "...", "action": "...", "linkTitle": "...", "linkUrl": "..." }
Redirect the user to the link in data and they land on the DCS-hosted PIN page.
Follow the hint in message and check your parameters (action, cardId, and whether both redirect URLs are present and valid)
The user fails to set a PIN inside the page
The DCS guidance page redirects them to errorRedirectUrl; offer a retry entry point on that page, which can request a fresh guidance link
The guidance link has expired or has already been used
Guidance links are single-use; call the endpoint again to obtain a new one
Whether the PIN was set successfully is determined by which URL the guidance page redirects to, successRedirectUrl or errorRedirectUrl. If you need server-side asynchronous confirmation, see the card events in Webhook + WebSocket notifications.
PIN complexity and length rules (permitted number of digits, whether simple sequences or repeated digits are rejected, and so on) are enforced inside the DCS-hosted guidance page and are transparent to the partner, so you do not need to reimplement the validation in your own system. If the user enters a PIN that breaks the rules, the page tells them straight away and asks for another.
