获取卡敏感信息 - DCS Technical Documentation

📄 正文

无论您是否持有 PCI 资质，都可以让终端用户安全地查看自己卡片的完整卡号、CVV 与有效期——DCS 为这两类接入机构分别提供了密文回传与托管引导页两条路径。作为持牌、自有 BIN 的发卡机构，DCS 在传输层对卡敏感信息全程加密，敏感数据不以明文落地。卡敏感信息（完整 PAN、CVV2、有效期）属于受 PCI DSS 约束的高敏数据。在卡管理接口中，卡号仅以前 6 位 + 后 4 位（panFirst6 / panLast4）形式返回；要取得完整明文，必须走本页的安全获取流程。

安全须知

切勿在接入机构后端或任何持久化介质中存储解密后的卡敏感信息。
仅在确有必要（如用户主动点击「查看卡号」）时才发起获取请求。
始终使用最新的加密库；密钥（enterpriseSecret）须妥善保管，参见鉴权指南。

两条路径：先判断您是否持有 PCI 资质

DCS 按接入机构的 PCI 资质把客户分成两类，路径完全不同：

路径	适用对象	谁解密/展示明文	接入机构后端是否触碰明文
路径一 `retrieve-secure-card`	持有 PCI 资质的接入机构	接入机构后端解密、前端展示	是（密文回传后由接入机构解密）
路径二 `guidance-link`	无 PCI 资质的接入机构	DCS 托管页面直接呈现给终端用户	否（明文不经接入机构后端）

选择哪条路径不是由您「决策」，而是由您的 PCI 资质决定。无资质时请勿尝试调用路径一。

路径一：获取卡敏感信息（PCI 资质）

谁做：接入机构（后端调用 + 解密 + 前端展示）。仅适用于持有 PCI 资质的接入机构。

接口

POST /open-api/card/v1/retrieve-secure-card
Content-Type: application/json

鉴权头与签名见鉴权指南。

请求参数

字段	类型	必填	说明
`cardId`	String	是	卡 ID，最大长度 50

{
  "cardId": "card_xxxxxxxxxxxx"
}

响应

统一响应结构为 { code, message, messageDetail, data }（结构字段含义见鉴权指南统一说明）。data 内的敏感字段均为密文：

{
  "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 位认证标签）如下：

// 摘自官网卡管理文档 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 页面承载卡敏感信息的展示，明文不经过接入机构后端。接入机构只需获取一次性引导页链接，再让终端用户在前端打开。

接口

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 等）与各自必填字段见引导页。

{
  "type": "1",
  "cardId": "card_xxxxxxxxxxxx",
  "customerId": "cust_xxxxxxxxxxxx",
  "language": "zh",
  "theme": "default",
  "mode": "light",
  "userAgent": "Mozilla/5.0 ...",
  "submitAutoClosed": "Y"
}

响应

data 为一个字符串，即可供终端用户打开的引导页链接：

{
  "code": "...",
  "message": "...",
  "messageDetail": { },
  "data": "https://<DCS 托管引导页 URL>"
}

将该链接交由终端用户在前端打开，DCS 托管页面会直接呈现完整卡号、CVV 与有效期，全程不经接入机构后端。

引导页链接使用存入 Redis 的临时 Token：校验成功后即删除，因此是一次性凭证，并同时受 TTL 限制。请获取后立即交由终端用户打开，不要缓存或复用。服务端会校验卡片与用户/企业归属；免鉴权的公共校验接口为 /card-bridge/redirect/public/v1/secret-validate 与 /card-bridge/redirect/public/v1/check-token-valid。

前置条件

已成功发行卡片并取得 cardId（参见开卡流程）。
路径一：已与 DCS 确认接入机构持有 PCI 资质，并妥善持有 enterpriseSecret。
路径二：已确认所属 customerId 与 cardId 的归属关系。

下一步

取到卡敏感信息后，可继续了解卡管理中的冻结/解冻、重置 PIN 与注销操作；加解密与密钥保管细节见鉴权指南。

​📄 正文

​两条路径：先判断您是否持有 PCI 资质

​路径一：获取卡敏感信息（PCI 资质）

​接口

​请求参数

​响应

​解密

​路径二：托管引导页查看（无 PCI 资质）

​接口

​请求参数（卡信息查询场景 type=1）

​响应

​前置条件

​下一步