H5 KYC / Card Application Guidance Page - DCS Technical Documentation

Many sensitive actions (KYC selfie capture, viewing the full card number, setting or resetting a PIN) should not pass through your backend at all; they are completed on the front end by a DCS-hosted page. That is exactly what the hosted guidance page mechanism is for:

Your backend calls the issuing API (/redirect/v{1,2}/guidance-link) with the page type and the end user identifier;
DCS returns a guidance link carrying a one-time secret (in the response data field);
You hand that link to your front end to open, either as a direct redirect, a new window, or embedded in a WebView or IFrame (for integration conventions see Web SDK / Front-end Integration);
When the DCS page opens, it uses the secret in the link to look up the context (Validating the guidance link) and renders the page once the link is confirmed legitimate;
Once the user finishes or fails, the DCS page redirects back to your site using the successRedirectUrl / errorRedirectUrl you supplied.

Calling the H5 guidance page and redirecting back

This page covers only the client-facing endpoints: guidance-link and public/secret-validate. Paths under internal or private, such as /internal/redirect/v1/h5 and /redirect/private/v1/h5, are internal DCS service-to-service APIs, not client-facing APIs you can call, and are not described here.

1. Issuing a guidance link

The guidance-link endpoint is:

Endpoint	Card identifier field
`POST /redirect/v2/guidance-link`	`cardId` (unique card ID)

The card is identified exactly by cardId rather than by the last four digits of the card number, which are not guaranteed to be unique across the cards of a single user.

Request headers

Header	Required	Description
`Content-Type`	REQUIRED	Fixed to `application/json`

This API is also subject to DCS authentication and IP whitelisting; for the header signing rules see the Authentication Guide.

Request fields

Field	Type	Required	Constraints / values	Description
`action`	string	REQUIRED	Enum, see Guidance page types (`action` enum)	Type of guidance page
`externalUserId`	string	REQUIRED	≤50	User ID
`cardId`	string	Conditional	—	Unique card ID, required for card-related actions
`language`	string	—	≤10, see Languages (`language` enum)	Language of the guidance page for the client-facing `guidance-link`
`theme`	string	—	≤10; the official description says it “cannot be empty”, so always send a value, e.g. `blue`	Theme
`mode`	string	—	≤10; the official description says it “cannot be empty”, so always send a value, `dark` / `light`	Light or dark mode
`primaryColor`	string	—	≤7, hex starting with `#`, e.g. `#FFFFFF`	Primary colour
`successRedirectUrl`	string	REQUIRED	≤300	Redirect URL on success. Consider appending your own correlation parameters (an order number, for example) so you can resume the flow when the user comes back
`errorRedirectUrl`	string	REQUIRED	≤300	Redirect URL on failure. Consider appending your own correlation parameters so you can resume the flow when the user comes back
`referer`	string	—	≤300	Referring origin, used for security checks
`userAgent`	string	—	≤300	User agent string, used for security checks
`selectCardPageShow`	string	—	≤1, `0`=do not skip / `1`=skip	Whether to show the card selection page when the user has only one card
`nationality`	string	—	Two-letter uppercase country code (may be empty or `null`), e.g. `SG`	Nationality. Only takes effect when `action=KYC_GUIDE`
`selectNationalityShow`	string	—	≤1, `0`=do not skip / `1`=skip	Whether to show the nationality selection page. Only takes effect when `action=KYC_GUIDE`
`applyId`	string	Conditional (KYC_EXTRA_DOC)	≤300; required when `action=KYC_EXTRA_DOC`	The related card application ID

The type of guidance page is controlled by action, and the accepted language values are listed below. Treat the fields on this page as authoritative: otpStatus, kycTicketId, CN/EN and similar parameters do not belong to this API.

Guidance page types (`action` enum)

Seven values are accepted:

`action`	Meaning
`KYC_GUIDE`	KYC guidance page
`CARD_INFO`	Card information (view card details)
`CREATE_PHYSICAL_CARD`	Apply for a physical card
`ACTIVE_PHYSICAL_CARD`	Activate a physical card
`UPDATE_PIN`	Update the PIN
`TRAVEL_RULE`	Update the user’s Travel Rule information
`KYC_EXTRA_DOC`	Supply additional KYC information

Languages (`language` enum)

language takes lowercase, hyphenated values and is case-sensitive, with seven accepted values (the same convention as the Quickstart). Any value outside this whitelist is silently downgraded to the default language, with no error returned:

`language`	Language
`zh`	Chinese (Simplified)
`en`	English
`ko`	Korean
`ja`	Japanese
`zh-Hant`	Chinese (Traditional)
`th`	Thai
`vi`	Vietnamese

Request example (v2, masked)

curl --location 'https://{dicard-server}/redirect/v2/guidance-link' \
  --header 'Content-Type: application/json' \
  --data '{
    "action": "KYC_GUIDE",
    "externalUserId": "ext_user_********",
    "cardId": "card_********",
    "language": "en",
    "theme": "blue",
    "mode": "dark",
    "primaryColor": "#FFFFFF",
    "successRedirectUrl": "https://your-app.example.com/kyc/success",
    "errorRedirectUrl": "https://your-app.example.com/kyc/error",
    "referer": "https://your-app.example.com",
    "selectCardPageShow": "0",
    "nationality": "SG",
    "selectNationalityShow": "1",
    "applyId": "apply_********"
  }'

Response

Every guidance API returns the common response envelope. The issued guidance link comes back in data (a string), not in a top-level linkUrl.

{
  "code": "SYS_SUCCESS",
  "message": null,
  "messageDetail": {
    "message": null,
    "title": null,
    "type": null,
    "icon": null,
    "action": null,
    "linkTitle": null,
    "linkUrl": null
  },
  "data": "https://{h5-host}/guidance?secret=<one-time-secret>"
}

Field	Type	Description
`code`	string	Business status code; `SYS_SUCCESS` on success, and this is what you check to decide success
`message`	string	Short message, usually `null` on success
`messageDetail`	object	Detailed prompt object (`message` / `title` / `type` / `icon` / `action` / `linkTitle` / `linkUrl`), whose fields are usually all `null` on success
`data`	string	The generated guidance page link, which you hand to your front end to open

When messageDetail is populated: on a normal success its fields are usually all null. It is filled in when the flow needs to show an extra prompt to you or to the end user, such as guidance copy for a redirect or a retry link. type then identifies the message category, and linkTitle / linkUrl provide a clickable link.

The link in data carries a one-time secret. Read Validating the guidance link to understand its lifecycle, and never expose the full link in logs or screenshots.

2. Redirecting back to your site

Once the user finishes, abandons or fails on the DCS-hosted page, DCS redirects to the address you supplied when the link was issued:

Success → successRedirectUrl
Failure or cancellation → errorRedirectUrl

Both URLs are limited to 300 characters. Consider carrying your own correlation parameters (an order number, for example) on the URL so you can resume the business flow when the user returns, but never put sensitive parameters there in clear text.

3. Validating the guidance link

The one-time secret inside a guidance link is looked up by the DCS-hosted page when the page opens, both to confirm that the link is legitimate and to retrieve the user context bound to it. This is a client-facing public endpoint:

GET /redirect/public/v1/secret-validate?secret=<secret>

Parameter	Required	Description
`secret`	REQUIRED	The one-time security code carried in the guidance link

Response (masked example)

{
  "code": "SYS_SUCCESS",
  "message": null,
  "messageDetail": { },
  "data": {
    "userId": 0,
    "externalUserId": "ext_user_********",
    "mobileCode": "+65",
    "mobile": "+65*****678",
    "email": "u***@example.com",
    "channel": "********",
    "allowAccessDecard": false,
    "successRedirectUrl": "https://your-app.example.com/kyc/success",
    "errorRedirectUrl": "https://your-app.example.com/kyc/error",
    "referer": "https://your-app.example.com",
    "userAgent": "********",
    "cardId": 0,
    "applyId": "apply_********",
    "params": {
      "key": ""
    }
  }
}

`data` field	Description
`userId`	Internal DCS user ID
`externalUserId`	User ID on the partner side
`mobileCode` / `mobile`	End user’s dialling code and mobile number
`email`	End user’s email address
`channel`	Channel identifier
`allowAccessDecard`	Whether access to DeCard is allowed
`successRedirectUrl` / `errorRedirectUrl`	The redirect addresses supplied when the link was issued
`referer` / `userAgent`	The security-check values supplied when the link was issued
`cardId` / `applyId`	The related card and card application
`params`	Additional parameters

In the example userId and cardId are 0, the default value for a number. The real values are internal DCS numeric IDs and are never 0; the example only illustrates the structure after masking.

PII red line: this response contains genuine personal data about the end user, including mobile / mobileCode / email / externalUserId. Every value shown above is a masked placeholder. During integration and operations it is strictly forbidden to keep real values in logs, tickets or documents shared outside your organization. Validation is normally initiated by the DCS-hosted page itself, so you rarely need to call this endpoint directly.

4. Error handling

When guidance-link fails, the response envelope returns a code other than SYS_SUCCESS together with a message describing the error. Common failure scenarios:

Error scenario	Common cause
Parameter validation failed	`action` is outside the enum, a required field is missing (any of `action` / `externalUserId` / `successRedirectUrl` / `errorRedirectUrl` is empty), or `cardId` was omitted on a card-related action
User or card not found	The `externalUserId` or `cardId` does not exist in the DCS system
Secret expired or invalid	The `secret` in the guidance link has timed out or has already been used (`secret-validate` returns a non-success code)
Authentication failed	`Content-Type` is missing, or the signature is wrong (see the Authentication Guide)

Error response example (masked)

{
  "code": "PARAM_INVALID",
  "message": "Parameter validation failed: successRedirectUrl must not be empty",
  "messageDetail": {
    "message": null,
    "title": null,
    "type": null,
    "icon": null,
    "action": null,
    "linkTitle": null,
    "linkUrl": null
  },
  "data": null
}

The code value PARAM_INVALID above is illustrative. In a live integration, always work from the code and message actually returned.

Language codes are defined by this page

Use only the language codes listed on this page for the client-facing guidance-link (zh / en / ko / ja / zh-Hant / th / vi — lowercase, hyphenated, case-sensitive, maximum length 10). Any value outside this whitelist is silently downgraded to the default language.

How to embed the guidance link in your front end and communicate with it once you have the URL: Web SDK / Front-end Integration.
Authentication has to work before you can call this API: Authentication Guide.
Sumsub / POA document requirements: Compliance · KYC Documents.

​1. Issuing a guidance link

​Request headers

​Request fields

​Guidance page types (action enum)

​Languages (language enum)

​Request example (v2, masked)

​Response

​2. Redirecting back to your site

​3. Validating the guidance link

​4. Error handling

​Language codes are defined by this page

​Next steps / Related

1. Issuing a guidance link

Request headers

Request fields

Guidance page types (`action` enum)

Languages (`language` enum)

Request example (v2, masked)

Response

2. Redirecting back to your site

3. Validating the guidance link

4. Error handling

Language codes are defined by this page

Next steps / Related