管理卡片 PIN - DCS Technical Documentation

📄 正文

持卡人在 ATM 取现或部分线下 POS 消费时需要输入 PIN（卡片密码）。作为持牌、自有 BIN 的发卡机构，DCS 把 PIN 设置归入需在受信页面内完成的敏感操作：在 DeCard 托管模型下，PIN 的设置与更新不通过直连 API 完成，而是由您引导用户跳转到 DCS 托管的 H5 引导页，用户在页内自行设置 PIN——敏感的密码录入与加密都在 DCS 托管页内完成，不经过您的后端。

前置条件：您需要先成功开卡并拿到这张卡的 cardId。如果还不清楚如何申请，请先阅读申请卡。

为什么 PIN 操作使用引导页而非 API

DeCard 托管模型把 PIN 设置归到一类需要终端用户在受信页面内亲自完成的敏感操作（与 KYC、查看卡敏感信息、实体卡激活同属一类）。这些操作统一通过 重定向引导页（guidanceLink） 完成：

您的后端调用引导页接口，传入操作类型（action / type）和目标卡标识，拿到一个一次性引导链接。
您把用户跳转到该链接。
用户在 DCS 托管的 H5 页面内输入并提交新 PIN，页面完成校验与加密。
完成后页面按您预设的回跳地址把用户送回您的应用。

这样您无需在客户端或后端接触明文 PIN，降低了 PCI 与合规负担。

获取 PIN 引导链接

PIN 引导页复用统一的引导页接口，以 cardId 精确定位卡片。

接口	定位卡片字段	触发 PIN 的取值
`POST /redirect/v2/guidance-link`	`cardId`	`action = UPDATE_PIN`

引导页接口的完整参数表与回跳机制统一记录在 H5 KYC 与开卡引导页。本页只列与 PIN 场景直接相关的字段，避免重复。

请求字段（PIN 场景）

字段	类型	必填	说明
`action`	string	是	PIN 场景固定填 `UPDATE_PIN`（更新 PIN）
`externalUserId`	string	是	用户 ID，最大长度 50
`cardId`	string	是	目标卡 ID（`UPDATE_PIN` 等需操作具体卡片的 action 必填）
`successRedirectUrl`	string	是	设置成功后的回跳 URL，最大长度 300
`errorRedirectUrl`	string	是	设置失败后的回跳 URL，最大长度 300
`referer`	string	否	引用来源，用于安全校验，最大长度 300
`userAgent`	string	否	用户代理信息，用于安全校验，最大长度 300
`language`	string	否	`guidance-link` 引导页语言，小写连字符、大小写敏感：`zh` / `en` / `ko` / `ja` / `zh-Hant` / `th` / `vi`，最大长度 10
`selectCardPageShow`	string	否	多卡场景下是否跳过选卡页，`0`-不跳过 / `1`-跳过，最大长度 1
`theme`	string	否	主题，如 `blue`，最大长度 10
`mode`	string	否	明暗模式，如 `dark` / `light`，最大长度 10

必填字段为 action / externalUserId / successRedirectUrl / errorRedirectUrl / cardId。theme / mode 虽非必填，但建议总是传入（与查看卡敏感信息的建议一致）。另有 nationality（国籍，仅 KYC_GUIDE 生效）、selectNationalityShow（国籍选择页，仅 KYC_GUIDE 生效）、primaryColor（主色调 # 开头 hex）、applyId（补件场景必传）四个字段属于引导页完整参数，非 PIN 场景所需。完整字段表见 H5 KYC 与开卡引导页。

请求示例（V2，已脱敏）

curl -X POST "{{dicard-server}}/redirect/v2/guidance-link" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "UPDATE_PIN",
    "externalUserId": "<external-user-id>",
    "cardId": "<card-id>",
    "successRedirectUrl": "https://your-app.example.com/pin/done",
    "errorRedirectUrl": "https://your-app.example.com/pin/error",
    "language": "en",
    "theme": "blue",
    "mode": "light"
  }'

鉴权：上例为聚焦业务字段省略了鉴权头，实际调用时必须携带 X-DAPI-API-KEY / X-DAPI-SIGN / X-DAPI-TIMESTAMP / X-DAPI-NONCE（HMAC-SHA256 签名），规则见鉴权指南。

所有示例值均为占位符。切勿在请求或日志中写入真实的 externalUserId、cardId、API Key/Secret 或任何持卡人个人信息。

响应

引导页接口返回统一响应结构 { code, message, messageDetail, data }，成功时 code = SYS_SUCCESS，data 为引导页链接（字符串）。messageDetail 是一个提示对象（schema 含 message / title / type / icon / action / linkTitle / linkUrl 七个子字段），用于失败时承载结构化提示；成功时通常为 null。

{
  "code": "SYS_SUCCESS",
  "message": "...",
  "messageDetail": null,
  "data": "https://<dcs-hosted-guidance-page>/...?token=<one-time-token>"
}

失败时 messageDetail 可返回如下结构（各子字段均为字符串）： { "message": "...", "title": "...", "type": "...", "icon": "...", "action": "...", "linkTitle": "...", "linkUrl": "..." }

将 data 中的链接用于跳转，即可把用户带入 DCS 托管的 PIN 设置页。

设置 PIN 的完整时序

H5 设置 PIN 页面截图

用户跳转到引导链接后，在 DCS 托管页内完成 PIN 设置，流程如下（action=UPDATE_PIN）：

错误处理

情况	处理建议
响应 `code` 非 `SYS_SUCCESS`	按 `message` 提示，校验请求参数（`action` / `cardId` / 回跳 URL 是否齐全且合法）
用户在页内设置失败	DCS 引导页会把用户重定向到 `errorRedirectUrl`；请在该页给出重试入口（可重新获取引导链接）
引导链接已过期/被用过	引导链接为一次性使用，过期或失效后重新调用接口获取新链接

PIN 设置成功 / 失败的最终结果以引导页回跳到 successRedirectUrl / errorRedirectUrl 为准；如需服务端异步确认，请参阅 Webhook 通知中的卡片相关事件。

关于 PIN 规则

PIN 的复杂度与长度规则（位数范围、是否禁用简单序列/重复数字等）由 DCS 托管引导页内置校验，对接入机构透明——您无需在自有系统中实现校验逻辑。用户在托管页内若输入不合规的 PIN，页面会直接提示并要求重新输入。

下一步

卡片管理 · 概述——冻结/解冻、换卡、状态机
H5 KYC 与开卡引导页——引导页完整参数与回跳机制
查看卡敏感信息——同样通过引导页（action = CARD_INFO）完成

​📄 正文

​为什么 PIN 操作使用引导页而非 API

​获取 PIN 引导链接

​请求字段（PIN 场景）

​请求示例（V2，已脱敏）

​响应

​设置 PIN 的完整时序

​H5 设置 PIN 页面截图

​错误处理

​关于 PIN 规则

​下一步

📄 正文

为什么 PIN 操作使用引导页而非 API

获取 PIN 引导链接

请求字段（PIN 场景）

请求示例（V2，已脱敏）

响应

设置 PIN 的完整时序

H5 设置 PIN 页面截图

错误处理

关于 PIN 规则

下一步