H5 KYC 与开卡引导页 - DCS Technical Documentation

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

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

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

1. 签发引导链接

引导链接接口如下：

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

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

请求头

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

该接口同样受 DCS 鉴权与白名单约束，请求头签名规则见鉴权指南。

请求字段

字段	类型	必填	约束 / 取值	说明
`action`	string	REQUIRED	枚举，见引导页类型（action 枚举）	引导页类型
`externalUserId`	string	REQUIRED	≤50	用户 ID
`cardId`	string	条件必填	—	卡唯一 ID，卡相关动作时需要
`language`	string	—	≤10，见语言枚举	`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

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

引导页类型（`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 个合法值（与快速开始口径一致）；传入白名单以外的值会被静默降级为默认语言，不会报错：

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

请求示例（v2，脱敏）

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。

{
  "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	生成的引导页链接——把它交给前端打开

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

data 中的链接带一次性 secret，请按有效性校验的语义理解其生命周期；切勿在日志/截图中暴露完整链接。

2. 跳转回您的站点

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

成功 → successRedirectUrl
失败/取消 → errorRedirectUrl

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

3. 引导链接有效性校验

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

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

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

响应（脱敏示例）

{
  "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`	附加参数

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

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

4. 错误处理

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

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

错误响应示例（脱敏）

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

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

语言码以本页为准

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

下一步 / 相关

拿到引导链接后如何在前端嵌入并与之通信，见 Web SDK 与前端集成。
调用本接口前需先配通鉴权，见鉴权指南。
Sumsub/POA 证件要求见合规 · KYC 证件说明。

​1. 签发引导链接

​请求头

​请求字段

​引导页类型（action 枚举）

​语言（language 枚举）

​请求示例（v2，脱敏）

​响应

​2. 跳转回您的站点

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

​4. 错误处理

​语言码以本页为准

​下一步 / 相关

1. 签发引导链接

请求头

请求字段

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

语言（`language` 枚举）

请求示例（v2，脱敏）

响应

2. 跳转回您的站点

3. 引导链接有效性校验

4. 错误处理

语言码以本页为准

下一步 / 相关