> ## 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. # 获取卡敏感信息 > 说明具备和不具备 PCI 资质的接入机构如何安全展示完整卡号、CVV 和有效期。 ## 📄 正文 无论您是否持有 PCI 资质，都可以让终端用户安全地查看自己卡片的完整卡号、CVV 与有效期——DCS 为这两类接入机构分别提供了密文回传与托管引导页两条路径。作为持牌、自有 BIN 的发卡机构，DCS 在传输层对卡敏感信息全程加密，敏感数据不以明文落地。 卡敏感信息（完整 PAN、CVV2、有效期）属于受 PCI DSS 约束的高敏数据。在卡管理接口中，卡号仅以前 6 位 + 后 4 位（`panFirst6` / `panLast4`）形式返回；要取得完整明文，必须走本页的安全获取流程。 **安全须知** * 切勿在接入机构后端或任何持久化介质中存储解密后的卡敏感信息。 * 仅在确有必要（如用户主动点击「查看卡号」）时才发起获取请求。 * 始终使用最新的加密库；密钥（`enterpriseSecret`）须妥善保管，参见[鉴权指南](../../integration-resources/authentication)。 ### 两条路径：先判断您是否持有 PCI 资质 DCS 按接入机构的 PCI 资质把客户分成两类，路径完全不同： 获取卡敏感信息的两条路径 获取卡敏感信息的两条路径 | 路径 | 适用对象 | 谁解密/展示明文 | 接入机构后端是否触碰明文 | | -------------------------- | ------------------ | ----------------- | --------------- | | 路径一 `retrieve-secure-card` | **持有 PCI 资质**的接入机构 | 接入机构后端解密、前端展示 | 是（密文回传后由接入机构解密） | | 路径二 `guidance-link` | **无 PCI 资质**的接入机构 | DCS 托管页面直接呈现给终端用户 | 否（明文不经接入机构后端） | > 选择哪条路径不是由您「决策」，而是由您的 **PCI 资质**决定。无资质时请勿尝试调用路径一。 *** ### 路径一：获取卡敏感信息（PCI 资质） > 谁做：**接入机构**（后端调用 + 解密 + 前端展示）。仅适用于持有 PCI 资质的接入机构。 #### 接口 ```http theme={null} POST /open-api/card/v1/retrieve-secure-card Content-Type: application/json ``` 鉴权头与签名见[鉴权指南](../../integration-resources/authentication)。 #### 请求参数 | 字段 | 类型 | 必填 | 说明 | | -------- | ------ | -- | ------------ | | `cardId` | String | 是 | 卡 ID，最大长度 50 | ```json theme={null} { "cardId": "card_xxxxxxxxxxxx" } ``` #### 响应 统一响应结构为 `{ code, message, messageDetail, data }`（结构字段含义见[鉴权指南](../../integration-resources/authentication)统一说明）。`data` 内的敏感字段均为**密文**： ```json theme={null} { "code": "...", "message": "...", "messageDetail": { }, "data": { "cardId": "card_xxxxxxxxxxxx", "pan": "<密文：完整卡号>", "cvv2": "<密文：CVV2>", "expireDate": "<密文：有效期，明文格式 mm/yy>", "iv": "<本次加密使用的 IV，Base64>" } } ``` | 字段 | 类型 | 说明 | | ------------ | ------ | ---------------------------- | | `cardId` | String | 卡 ID | | `pan` | String | 完整卡号（**密文**） | | `cvv2` | String | CVV2（**密文**） | | `expireDate` | String | 有效期（**密文**），解密后明文格式为 `mm/yy` | | `iv` | String | 本次加密所用初始化向量（IV），用于解密上述三个密文字段 | #### 解密 `pan` / `cvv2` / `expireDate` 三个字段以 **AES-GCM** 加密，密钥为接入机构入驻时分配的 `enterpriseSecret`（Base64 解码后作为密钥字节，密钥位长由解码字节数决定），初始化向量为响应中随附的 `iv`。官方 Java 解密实现（`AES/GCM/NoPadding`、12 字节 IV、128 位认证标签）如下： ```java theme={null} // 摘自官网卡管理文档 AESUtil（节选） public static String decryptGCM(String base64Ciphertext, String enterpriseSecret, String base64IV) { SecretKey key = new SecretKeySpec(Base64.getDecoder().decode(enterpriseSecret), "AES"); byte[] iv = Base64.getDecoder().decode(base64IV); byte[] ciphertext = Base64.getDecoder().decode(base64Ciphertext); Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding", "SunJCE"); GCMParameterSpec spec = new GCMParameterSpec(128, iv); // 128 位认证标签 cipher.init(Cipher.DECRYPT_MODE, key, spec); return new String(cipher.doFinal(ciphertext), StandardCharsets.UTF_8); } ``` 三个字段共用同一个 `iv`。解密后即可在前端展示，**请勿回写或存储**。 > 加密规范：密钥取自 `enterpriseSecret` 经 Base64 解码后的字节（位长随 Secret 长度决定，当前为 16 字节 / AES-128）；每次请求随机生成 12 字节 IV，并通过响应 `iv` 返回；128 位 GCM Tag 附在密文末尾，`ciphertext + authTag` 整体做 Base64 编码。调用方还必须在 PCI 白名单中，`cardId` 必须属于当前 Enterprise，且卡状态必须为 `ACTIVATED`。 *** ### 路径二：托管引导页查看（无 PCI 资质） > 谁做：**接入机构**发起获取链接，**DCS** 托管页面并向终端用户呈现明文。 无 PCI 资质时，由 DCS 提供一个托管 H5 页面承载卡敏感信息的展示，明文**不经过接入机构后端**。接入机构只需获取一次性引导页链接，再让终端用户在前端打开。 #### 接口 ```http theme={null} POST /open-api/card-redirect/v1/guidance-link Content-Type: application/json ``` #### 请求参数（卡信息查询场景 `type=1`） | 字段 | 类型 | 必填 | 说明 | | ----------------------- | ------ | ------------ | ------------------------------------------------ | | `type` | String | 是 | 固定传 `1`（卡信息查询） | | `cardId` | String | `type=1` 时必填 | 卡 ID，最大长度 50 | | `customerId` | String | 是 | 用户 ID，最大长度 50 | | `language` | String | 是 | 语言，`zh` / `en`（非 zh 国家映射为 en） | | `theme` | String | 是 | 主题，最大长度 10，例：`default` / `blue`（`blue` 仅支持卡信息查询） | | `mode` | String | 是 | `light` / `dark` | | `userAgent` | String | 是 | 最大长度 300 | | `successfulRedirectUrl` | String | 否 | 成功后跳转 URL，最大长度 200 | | `errorRedirectUrl` | String | 否 | 失败后跳转 URL，最大长度 200 | | `submitAutoClosed` | String | 否 | 提交成功后是否自动关闭页面：`Y` / `N` | | `primaryColor` | String | 否 | 主色调，最大长度 7，例：`#FFFFFF` | > `otpStatus` 仅在 `type=2`（Set PIN）/`type=3`（重置 PIN）时必填，卡信息查询（`type=1`）无需传入。引导页其余 `type` 取值（人脸认证、KYC 等）与各自必填字段见[引导页](../kyc/h5-kyc-guidance)。 ```json theme={null} { "type": "1", "cardId": "card_xxxxxxxxxxxx", "customerId": "cust_xxxxxxxxxxxx", "language": "zh", "theme": "default", "mode": "light", "userAgent": "Mozilla/5.0 ...", "submitAutoClosed": "Y" } ``` #### 响应 `data` 为一个字符串，即可供终端用户打开的引导页链接： ```json theme={null} { "code": "...", "message": "...", "messageDetail": { }, "data": "https://" } ``` 将该链接交由终端用户在前端打开，DCS 托管页面会直接呈现完整卡号、CVV 与有效期，全程不经接入机构后端。 > 引导页链接使用存入 Redis 的临时 Token：校验成功后即删除，因此是一次性凭证，并同时受 TTL 限制。请获取后立即交由终端用户打开，不要缓存或复用。服务端会校验卡片与用户/企业归属；免鉴权的公共校验接口为 `/card-bridge/redirect/public/v1/secret-validate` 与 `/card-bridge/redirect/public/v1/check-token-valid`。 *** ### 前置条件 * 已成功发行卡片并取得 `cardId`（参见[开卡流程](./card-issuing)）。 * 路径一：已与 DCS 确认接入机构持有 PCI 资质，并妥善持有 `enterpriseSecret`。 * 路径二：已确认所属 `customerId` 与 `cardId` 的归属关系。 ## 下一步 取到卡敏感信息后，可继续了解[卡管理](./card-management)中的冻结/解冻、重置 PIN 与注销操作；加解密与密钥保管细节见[鉴权指南](../../integration-resources/authentication)。