> ## 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. # 管理卡片 PIN > 讲在 DeCard 托管模式下 PIN 的设置/更新为何走托管引导页而非直连 API，以及如何获取 PIN 引导链接（action=UPDATE_PIN）、完整时序与错误处理。 ## 📄 正文 持卡人在 ATM 取现或部分线下 POS 消费时需要输入 PIN（卡片密码）。作为持牌、自有 BIN 的发卡机构，DCS 把 PIN 设置归入需在受信页面内完成的敏感操作：在 DeCard 托管模型下，**PIN 的设置与更新不通过直连 API 完成**，而是由您引导用户跳转到 **DCS 托管的 H5 引导页**，用户在页内自行设置 PIN——敏感的密码录入与加密都在 DCS 托管页内完成，不经过您的后端。 > **前置条件**：您需要先成功开卡并拿到这张卡的 `cardId`。如果还不清楚如何申请，请先阅读[申请卡](./issuing-cards)。 ### 为什么 PIN 操作使用引导页而非 API DeCard 托管模型把 PIN 设置归到一类需要终端用户在受信页面内亲自完成的敏感操作（与 KYC、查看卡敏感信息、实体卡激活同属一类）。这些操作统一通过 **重定向引导页（guidanceLink）** 完成： 1. 您的后端调用引导页接口，传入操作类型（`action` / `type`）和目标卡标识，拿到一个一次性引导链接。 2. 您把用户跳转到该链接。 3. 用户在 DCS 托管的 H5 页面内输入并提交新 PIN，页面完成校验与加密。 4. 完成后页面按您预设的回跳地址把用户送回您的应用。 这样您**无需在客户端或后端接触明文 PIN**，降低了 PCI 与合规负担。 ## 获取 PIN 引导链接 PIN 引导页复用统一的引导页接口，以 `cardId` 精确定位卡片。 | 接口 | 定位卡片字段 | 触发 PIN 的取值 | | :-------------------------------- | :------- | :-------------------- | | `POST /redirect/v2/guidance-link` | `cardId` | `action = UPDATE_PIN` | > 引导页接口的**完整参数表与回跳机制**统一记录在 [H5 KYC 与开卡引导页](../../integration-resources/h5-kyc-guidance)。本页只列与 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` 虽非必填，但建议总是传入（与[查看卡敏感信息](./viewing-encrypted-card-details)的建议一致）。 > > 另有 `nationality`（国籍，仅 `KYC_GUIDE` 生效）、`selectNationalityShow`（国籍选择页，仅 `KYC_GUIDE` 生效）、`primaryColor`（主色调 `#` 开头 hex）、`applyId`（补件场景必传）四个字段属于引导页完整参数，非 PIN 场景所需。完整字段表见 [H5 KYC 与开卡引导页](../../integration-resources/h5-kyc-guidance)。 ### 请求示例（V2，已脱敏） ```bash theme={null} curl -X POST "{{dicard-server}}/redirect/v2/guidance-link" \ -H "Content-Type: application/json" \ -d '{ "action": "UPDATE_PIN", "externalUserId": "", "cardId": "", "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 签名），规则见 [鉴权指南](../../integration-resources/overview)。 所有示例值均为占位符。**切勿**在请求或日志中写入真实的 `externalUserId`、`cardId`、API Key/Secret 或任何持卡人个人信息。 ### 响应 引导页接口返回统一响应结构 `{ code, message, messageDetail, data }`，成功时 `code = SYS_SUCCESS`，`data` 为引导页链接（字符串）。`messageDetail` 是一个**提示对象**（schema 含 `message` / `title` / `type` / `icon` / `action` / `linkTitle` / `linkUrl` 七个子字段），用于失败时承载结构化提示；成功时通常为 `null`。 ```json theme={null} { "code": "SYS_SUCCESS", "message": "...", "messageDetail": null, "data": "https:///...?token=" } ``` > 失败时 `messageDetail` 可返回如下结构（各子字段均为字符串）： > `{ "message": "...", "title": "...", "type": "...", "icon": "...", "action": "...", "linkTitle": "...", "linkUrl": "..." }` 将 `data` 中的链接用于跳转，即可把用户带入 DCS 托管的 PIN 设置页。 ## 设置 PIN 的完整时序 设置 PIN 的完整时序 设置 PIN 的完整时序 ### H5 设置 PIN 页面截图 用户跳转到引导链接后，在 DCS 托管页内完成 PIN 设置，流程如下（`action=UPDATE_PIN`）： ## 错误处理 | 情况 | 处理建议 | | :------------------------ | :---------------------------------------------------------- | | 响应 `code` 非 `SYS_SUCCESS` | 按 `message` 提示，校验请求参数（`action` / `cardId` / 回跳 URL 是否齐全且合法） | | 用户在页内设置失败 | DCS 引导页会把用户重定向到 `errorRedirectUrl`；请在该页给出重试入口（可重新获取引导链接） | | 引导链接已过期/被用过 | 引导链接为一次性使用，过期或失效后重新调用接口获取新链接 | > PIN 设置成功 / 失败的最终结果以引导页回跳到 `successRedirectUrl` / `errorRedirectUrl` 为准；如需服务端异步确认，请参阅 [Webhook 通知](../../integration-resources/webhook-websocket)中的卡片相关事件。 ## 关于 PIN 规则 PIN 的复杂度与长度规则（位数范围、是否禁用简单序列/重复数字等）由 DCS 托管引导页内置校验，对接入机构透明——您无需在自有系统中实现校验逻辑。用户在托管页内若输入不合规的 PIN，页面会直接提示并要求重新输入。 ## 下一步 * [卡片管理 · 概述](./overview)——冻结/解冻、换卡、状态机 * [H5 KYC 与开卡引导页](../../integration-resources/h5-kyc-guidance)——引导页完整参数与回跳机制 * [查看卡敏感信息](./viewing-encrypted-card-details)——同样通过引导页（`action = CARD_INFO`）完成