> ## 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 与开卡引导页

> DCS 将 KYC、查看卡信息、申请或激活实体卡、更新 PIN、旅行规则等终端用户操作以托管 H5 页面形式提供。本页介绍如何生成引导链接，让终端用户从您的应用或网页进入 DCS 托管页面完成操作。

很多敏感动作（KYC 人脸采集、查看完整卡号、设置/重置 PIN 等）**不应**经过您的后端，而由 DCS 托管页面在前端直接完成。引导页机制就是为此设计：

1. 您后端调用 **签发接口**（`/redirect/v{1,2}/guidance-link`），传入引导页类型与终端用户标识；
2. DCS 返回一条**带一次性 secret 的引导链接**（在响应 `data` 字段中）；
3. 您把该链接交给前端打开（直接跳转、新窗口，或嵌入 WebView / IFrame——集成约定见 [Web SDK 与前端集成](../sdk/web-sdk)）；
4. DCS 页面打开时，会用链接中的 secret 反查上下文（[引导链接有效性校验](#3-引导链接有效性校验)），确认合法后渲染对应页面；
5. 用户完成或失败后，DCS 页面按您传入的 `successRedirectUrl` / `errorRedirectUrl` 重定向回您的站点。

<Frame>
  <img className="block dark:hidden" src="https://mintcdn.com/dcs-0bf7a937/oUoeUKtwWWK2o-Li/imgs/diagrams/va-h5-guidance-flow-light.svg?fit=max&auto=format&n=oUoeUKtwWWK2o-Li&q=85&s=3fe9ff697c4b9537b76bee65e90876c9" alt="H5 引导页的调用与回跳流程" width="664" height="396" data-path="imgs/diagrams/va-h5-guidance-flow-light.svg" />

  <img className="hidden dark:block" src="https://mintcdn.com/dcs-0bf7a937/oUoeUKtwWWK2o-Li/imgs/diagrams/va-h5-guidance-flow-dark.svg?fit=max&auto=format&n=oUoeUKtwWWK2o-Li&q=85&s=f44e819dd56b6abbfdb632759dcc919d" alt="H5 引导页的调用与回跳流程" width="664" height="396" data-path="imgs/diagrams/va-h5-guidance-flow-dark.svg" />
</Frame>

<Note>
  本页只覆盖**接入机构可调用的公开接口**：`guidance-link` 与 `public/secret-validate`。`/internal/redirect/v1/h5`、`/redirect/private/v1/h5` 等 `internal` / `private` 路径为 DCS 内部服务间接口，**不是您可调用的公开接口**，本页不予描述。
</Note>

***

## 1. 签发引导链接

引导链接接口如下：

| 接口                                | 卡定位字段            |
| :-------------------------------- | :--------------- |
| `POST /redirect/v2/guidance-link` | `cardId`（卡唯一 ID） |

> 卡片以 `cardId` 精确定位，不使用卡号后四位（同一用户名下后四位可能不唯一，存在歧义）。

### 请求头

| Header         | 必填       | 说明                    |
| :------------- | :------- | :-------------------- |
| `Content-Type` | REQUIRED | 固定 `application/json` |

> 该接口同样受 DCS 鉴权与白名单约束，请求头签名规则见 [鉴权指南](./overview)。

### 请求字段

| 字段                      | 类型     | 必填                    | 约束 / 取值                                    | 说明                                      |
| :---------------------- | :----- | :-------------------- | :----------------------------------------- | :-------------------------------------- |
| `action`                | string | REQUIRED              | 枚举，见 [引导页类型（action 枚举）](#引导页类型（action-枚举）) | 引导页类型                                   |
| `externalUserId`        | string | REQUIRED              | ≤50                                        | 用户 ID                                   |
| `cardId`                | string | 条件必填                  | —                                          | 卡唯一 ID，卡相关动作时需要                         |
| `language`              | string | —                     | ≤10，见 [语言枚举](#语言（language-枚举）)             | `guidance-link` 引导页语言                   |
| `theme`                 | string | —                     | ≤10；官方描述标注「不能为空」，建议始终传值，eg `blue`          | 主题                                      |
| `mode`                  | string | —                     | ≤10；官方描述标注「不能为空」，建议始终传值，`dark` / `light`   | 明暗模式                                    |
| `primaryColor`          | string | —                     | ≤7，`#` 开头 hex，eg `#FFFFFF`                 | 主色调                                     |
| `successRedirectUrl`    | string | REQUIRED              | ≤300                                       | 成功后重定向 URL。建议携带业务关联参数（如订单号）以便用户跳回后续业务流程 |
| `errorRedirectUrl`      | string | REQUIRED              | ≤300                                       | 失败后重定向 URL。建议携带业务关联参数以便用户跳回后续业务流程       |
| `referer`               | string | —                     | ≤300                                       | 引用来源，用于安全校验                             |
| `userAgent`             | string | —                     | ≤300                                       | 用户代理信息，用于安全校验                           |
| `selectCardPageShow`    | string | —                     | ≤1，`0`=不跳过 / `1`=跳过                        | 仅一张卡时，是否展示选卡页面                          |
| `nationality`           | string | —                     | 两位大写国家码（可空 / 可 `null`），eg `SG`             | 国籍。**仅 `action=KYC_GUIDE` 时生效**         |
| `selectNationalityShow` | string | —                     | ≤1，`0`=不跳过 / `1`=跳过                        | 是否展示国籍选择页面。**仅 `action=KYC_GUIDE` 时生效** |
| `applyId`               | string | 条件必填（KYC\_EXTRA\_DOC） | ≤300；`action=KYC_EXTRA_DOC` 时必填            | 关联的卡申请单 ID                              |

<Warning>
  引导页类型由 `action` 控制，语言取值见下表；请以本页字段为准（`otpStatus`、`kycTicketId`、`CN/EN` 等参数不属于本接口）。
</Warning>

#### 引导页类型（`action` 枚举）

共 7 个合法值：

| `action`               | 含义               |
| :--------------------- | :--------------- |
| `KYC_GUIDE`            | KYC 引导页          |
| `CARD_INFO`            | 卡信息（查看卡片详情）      |
| `CREATE_PHYSICAL_CARD` | 申请实体卡            |
| `ACTIVE_PHYSICAL_CARD` | 实体卡激活            |
| `UPDATE_PIN`           | 更新 PIN           |
| `TRAVEL_RULE`          | 更新用户 Travel Rule |
| `KYC_EXTRA_DOC`        | KYC 补充信息         |

#### 语言（`language` 枚举）

`language` 取值为**小写连字符**形式且**大小写敏感**，共 7 个合法值（与 [快速开始](../getting-started/quickstart) 口径一致）；传入白名单以外的值会被静默降级为默认语言，不会报错：

| `language` | 语言     |
| :--------- | :----- |
| `zh`       | 中文（简体） |
| `en`       | 英文     |
| `ko`       | 韩文     |
| `ja`       | 日文     |
| `zh-Hant`  | 中文（繁体） |
| `th`       | 泰文     |
| `vi`       | 越南文    |

### 请求示例（v2，脱敏）

```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_********"
  }'
```

### 响应

所有引导接口返回统一结构；**签发出的引导链接在 `data`（string）字段中返回，不是顶层 `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=<one-time-secret>"
}
```

| 字段              | 类型     | 说明                                                                                                 |
| :-------------- | :----- | :------------------------------------------------------------------------------------------------- |
| `code`          | string | 业务状态码，成功为 `SYS_SUCCESS`（判断成功以此为准）                                                                  |
| `message`       | string | 简要信息，成功通常为 `null`                                                                                  |
| `messageDetail` | object | 详细提示对象（`message` / `title` / `type` / `icon` / `action` / `linkTitle` / `linkUrl`），成功通常各字段为 `null` |
| `data`          | string | **生成的引导页链接**——把它交给前端打开                                                                             |

<Note>
  **`messageDetail` 非空场景**：正常成功时 `messageDetail` 各字段通常为 `null`。当流程需向您或终端用户展示额外提示（如跳转引导文案、再试链接等）时，`messageDetail` 会被填充——例如 `type` 标识消息类别、`linkTitle` / `linkUrl` 给出可点击链接。
</Note>

<Warning>
  `data` 中的链接带一次性 `secret`，请按 [有效性校验](#3-引导链接有效性校验) 的语义理解其生命周期；**切勿在日志/截图中暴露完整链接**。
</Warning>

***

## 2. 跳转回您的站点

用户在 DCS 托管页面完成（或放弃/失败）后，DCS 会按您签发时传入的地址重定向：

* 成功 → `successRedirectUrl`
* 失败/取消 → `errorRedirectUrl`

> 两个 URL 均 ≤300 字符。建议在 URL 上携带您自己的业务关联参数（如订单号），以便用户跳回后续接业务流程；敏感参数请勿明文放入。

***

## 3. 引导链接有效性校验

引导链接里的一次性 `secret` 由 **DCS 托管页面在打开时**回查，用于确认链接合法并获取该链接绑定的用户上下文。该接口为**公开接口**：

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

| 参数       | 必填       | 说明             |
| :------- | :------- | :------------- |
| `secret` | REQUIRED | 引导链接中携带的一次性安全码 |

**响应（脱敏示例）**

```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` 字段                                 | 说明            |
| :---------------------------------------- | :------------ |
| `userId`                                  | DCS 内部用户 ID   |
| `externalUserId`                          | 接入机构侧用户 ID    |
| `mobileCode` / `mobile`                   | 终端用户手机区号 / 号码 |
| `email`                                   | 终端用户邮箱        |
| `channel`                                 | 渠道标识          |
| `allowAccessDecard`                       | 是否允许访问 DeCard |
| `successRedirectUrl` / `errorRedirectUrl` | 签发时传入的跳转地址    |
| `referer` / `userAgent`                   | 签发时传入的安全校验信息  |
| `cardId` / `applyId`                      | 关联卡片 / 卡申请单   |
| `params`                                  | 附加参数          |

<Note>
  示例中 `userId` 和 `cardId` 为 `0`（number 默认值），实际值为 DCS 内部数字 ID，不会是 0；以上仅为脱敏后的结构示例。
</Note>

<Warning>
  **PII 红线**：该响应含终端用户 `mobile` / `mobileCode` / `email` / `externalUserId` 等真实个人信息。上述示例值全部为脱敏占位；接入与运维过程中**严禁**在日志、工单、外发文档中保留真实值。校验通常由 DCS 托管页面自身发起，您一般无需直接调用。
</Warning>

***

## 4. 错误处理

`guidance-link` 发生错误时，响应结构统一返回 `code`（非 `SYS_SUCCESS`）和 `message`（错误描述）。常见失败场景：

| 错误场景          | 常见原因                                                                                                                   |
| :------------ | :--------------------------------------------------------------------------------------------------------------------- |
| 参数校验失败        | `action` 不在枚举值内、必填字段缺失（`action` / `externalUserId` / `successRedirectUrl` / `errorRedirectUrl` 任一为空）、`cardId` 卡相关动作时未传 |
| 用户/卡不存在       | `externalUserId` 或 `cardId` 在 DCS 系统中不存在                                                                               |
| secret 已过期/无效 | 引导链接的 `secret` 超时或被使用过（`secret-validate` 返回非成功）                                                                        |
| 鉴权失败          | `Content-Type` 缺失、签名错误（见 [鉴权指南](./overview)）                                                                           |

**错误响应示例（脱敏）**

```json theme={null}
{
  "code": "PARAM_INVALID",
  "message": "参数校验失败：successRedirectUrl 不能为空",
  "messageDetail": {
    "message": null,
    "title": null,
    "type": null,
    "icon": null,
    "action": null,
    "linkTitle": null,
    "linkUrl": null
  },
  "data": null
}
```

<Warning>
  以上 `code` 值 `PARAM_INVALID` 为示意，实际接入时请以线上返回的 `code` 和 `message` 为准。
</Warning>

***

## 语言码以本页为准

接入时请只使用本页 `guidance-link` 列出的语言码（`zh` / `en` / `ko` / `ja` / `zh-Hant` / `th` / `vi`，小写连字符、大小写敏感，最大长度 10）；白名单以外的值会被静默降级为默认语言。

***

## 下一步 / 相关

* 拿到引导链接后如何在前端嵌入并与之通信，见 [Web SDK 与前端集成](../sdk/web-sdk)。
* 调用本接口前需先配通鉴权，见 [鉴权指南](./overview)。
* Sumsub/POA 证件要求见 [合规 · KYC 证件说明](../customer-success/kyc-documents)。