> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thedecard.com/llms.txt
> Use this file to discover all available pages before exploring further.
# H5 KYC / Card Application Guidance Page
> DCS delivers a number of end-user interactions (KYC, card details, applying for and activating a physical card, updating a PIN, Travel Rule and more) as hosted H5 pages. This page explains how to issue a guidance link that sends an end user from your app or website on a temporary detour to a DCS-hosted page to complete the task.
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:
1. Your backend calls the **issuing API** (`/redirect/v{1,2}/guidance-link`) with the page type and the end user identifier;
2. DCS returns a **guidance link carrying a one-time secret** (in the response `data` field);
3. 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](../sdk/web-sdk));
4. When the DCS page opens, it uses the secret in the link to look up the context ([Validating the guidance link](#3-validating-the-guidance-link)) and renders the page once the link is confirmed legitimate;
5. Once the user finishes or fails, the DCS page redirects back to your site using the `successRedirectUrl` / `errorRedirectUrl` you supplied.
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](./overview).
### Request fields
| Field | Type | Required | Constraints / values | Description |
| :---------------------- | :----- | :---------------------------- | :------------------------------------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `action` | string | REQUIRED | Enum, see [Guidance page types (`action` enum)](#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)](#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](../getting-started/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)
```bash theme={null}
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`.**
```json theme={null}
{
"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="
}
```
| 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](#3-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=
```
| Parameter | Required | Description |
| :-------- | :------- | :------------------------------------------------------ |
| `secret` | REQUIRED | The one-time security code carried in the guidance link |
**Response (masked example)**
```json theme={null}
{
"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](./overview)) |
**Error response example (masked)**
```json theme={null}
{
"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.
***
## Next steps / Related
* How to embed the guidance link in your front end and communicate with it once you have the URL: [Web SDK / Front-end Integration](../sdk/web-sdk).
* Authentication has to work before you can call this API: [Authentication Guide](./overview).
* Sumsub / POA document requirements: [Compliance · KYC Documents](../customer-success/kyc-documents).