查看卡敏感信息 - DCS Technical Documentation

📄 正文

出于安全与合规（PCI DSS）要求，卡的完整卡号（PAN）、CVV、有效期属于高敏数据，不会在常规卡查询接口中以明文返回——卡详情接口仅返回脱敏信息（如 cardMantissa 卡号后四位；完整卡号仅通过本页 H5 托管引导页安全展示）。作为持牌、自有 BIN 的发卡机构，DCS 在托管页面内完成敏感信息的安全呈现，让无 PCI 资质的接入机构也能合规地为终端用户展示卡面信息。要让终端用户查看完整卡面信息，必须走本页的安全展示流程。

DeCard 托管模式的唯一机制：H5 托管引导页

在 DeCard 托管模式下，DCS 不提供把卡密文回传到接入机构后端、再由接入机构自行解密的接口。展示完整卡面信息的唯一官方机制是 DCS 托管的 H5 引导页：接入机构调用引导页接口，传入 action=CARD_INFO，DCS 返回一个一次性引导页链接；接入机构把该链接交由终端用户在前端打开，完整卡号 / CVV / 有效期由 DCS 托管页面直接呈现给终端用户，明文全程不经过接入机构后端。

这种「明文只在 DCS 托管页面呈现、不落接入机构后端」的设计，使无 PCI 资质的接入机构也能安全地让终端用户查看卡面信息。

安全须知

切勿在接入机构后端或任何持久化介质中存储卡的完整卡号、CVV 或有效期。
仅在确有必要（如终端用户主动点击「查看卡号」）时才发起获取请求。
引导页链接为一次性临时凭证，建议获取后尽快交由终端用户打开，不要缓存或转发。

三步流程

DeCard 托管模式的安全展示流程可概括为三步： 步骤 1：调用引导页接口获取链接 — 接入机构后端调用 POST /redirect/v2/guidance-link，传入 action=CARD_INFO 及卡标识，DCS 返回一次性托管引导页链接（data 字段）。 步骤 2：将链接交由终端用户打开 — 接入机构将链接传递给终端用户前端，不要在接入机构后端打开或缓存该链接。 步骤 3：DCS 托管页面呈现卡面信息 — 终端用户在浏览器中打开链接，DCS 托管 H5 页直接呈现完整卡号、CVV 与有效期；明文全程不经过接入机构后端。

接口（推荐 V2，按 `cardId` 定位）

POST /redirect/v2/guidance-link
Content-Type: application/json

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

请求参数（卡信息查询场景 `action=CARD_INFO`）

字段	类型	必填	说明
`action`	String	是	固定传 `CARD_INFO`（卡信息）
`externalUserId`	String	是	用户 ID，最大长度 50
`successRedirectUrl`	String	是	成功后的重定向 URL，最大长度 300
`errorRedirectUrl`	String	是	失败后的重定向 URL，最大长度 300
`cardId`	String	是	卡 ID（V2 按 `cardId` 定位具体卡片，`CARD_INFO` 场景必填）
`referer`	String	否	引用来源，用于安全校验，最大长度 300
`userAgent`	String	否	用户代理信息，用于安全校验，最大长度 300
`language`	String	否	`guidance-link` 引导页语言，最大长度 10，小写连字符、大小写敏感：`zh` / `en` / `ko` / `ja` / `zh-Hant` / `th` / `vi`
`theme`	String	否	主题，最大长度 10，例：`blue`（建议传入）
`mode`	String	否	显示模式，最大长度 10，例：`dark` / `light`（建议传入）
`selectCardPageShow`	String	否	仅一张卡时：`0`-仍然展示选卡页 / `1`-跳过选卡页直接进入卡信息页，最大长度 1
`primaryColor`	String	否	主色调，最大长度 7，例：`#FFFFFF`（建议传入）

必填字段为 action / externalUserId / successRedirectUrl / errorRedirectUrl / cardId。theme / mode 虽非必填，但建议总是传入。

{
  "action": "CARD_INFO",
  "externalUserId": "<脱敏：用户 ID>",
  "cardId": "<脱敏：卡ID>",
  "successRedirectUrl": "https://your-app.example.com/card/ok",
  "errorRedirectUrl": "https://your-app.example.com/card/err",
  "language": "zh",
  "theme": "blue",
  "mode": "light"
}

响应

统一响应结构为 { code, message, messageDetail, data }（无 success 布尔字段；结构含义见鉴权指南统一说明）。成功时 code = SYS_SUCCESS，data 为一个字符串，即可供终端用户打开的引导页链接。messageDetail 是一个结构化提示对象（schema 含 message / title / type / icon / action / linkTitle / linkUrl 七个子字段），用于承载结构化提示；正常成功时各子字段为空字符串、由系统按需填充：

{
  "code": "SYS_SUCCESS",
  "message": "",
  "messageDetail": {
    "message": "",
    "title": "",
    "type": "",
    "icon": "",
    "action": "",
    "linkTitle": "",
    "linkUrl": ""
  },
  "data": "https://<DCS 托管引导页 URL>"
}

将该链接（data 字段，普通 URL 字符串）交由终端用户在前端打开，DCS 托管页面会直接呈现完整卡号、CVV 与有效期。

messageDetail 子字段说明

messageDetail 为结构化提示对象，包含七个子字段，用于承载业务提示或错误信息。正常成功时各子字段为空字符串，由系统按需填充：

子字段	类型	说明
`type`	String	消息类型：`INFO`（信息） / `WARN`（警告） / `ERROR`（错误）
`icon`	String	图标标识，前端可按此渲染对应图标
`action`	String	建议动作码，如 `RETRY` / `CONTACT_SUPPORT` 等
`message`	String	面向终端用户的业务提示正文
`title`	String	提示标题
`linkTitle`	String	可操作链接的标题文本
`linkUrl`	String	可操作链接的跳转地址

常见错误响应示例

失败时 code 即该错误对应的具体业务错误码（不存在通用失败码）。以下为卡处于冻结状态（非 NORMAL 状态不支持查询）的典型错误响应。注意：即使请求失败（messageDetail.type=ERROR），HTTP 状态码仍为 200；请以 code 而非 HTTP 状态码判断成功/失败：

{
  "code": "CARD_CARD_FROZEN_STATUS_UNSUPPORTED",
  "message": "card is frozen",
  "messageDetail": {
    "message": "卡片处于冻结状态，暂不支持查看卡信息",
    "title": "查询失败",
    "type": "ERROR",
    "icon": "error",
    "action": "RETRY",
    "linkTitle": "",
    "linkUrl": ""
  },
  "data": ""
}

messageDetail 各子字段在何种场景下填充、是否同时出现，请以实际返回为准。

引导页其余 action 取值（KYC 引导、申请/激活实体卡、更新 PIN、Travel Rule、KYC 补充信息等）及各自必填字段，见 H5 KYC 与开卡引导页。

前置条件

已成功发行卡片并取得 cardId，参见申请卡。
已确认该卡所属的 externalUserId 归属关系。
已确认卡状态：仅 NORMAL 状态的卡可查询/展示卡敏感信息。FROZEN 状态的卡发起查询会返回错误码 CARD_CARD_FROZEN_STATUS_UNSUPPORTED；其他非 NORMAL 状态同样不可查询。此外，LUMINARY 卡未缴年费时返回错误码 CARD_ANNUAL_FEE_NOT_CHARGED。完整状态机（虚拟卡 NORMAL / FROZEN / CANCELLED；实体卡另有独立状态机 UN_APPLY / INACTIVE / ACTIVE / REPLACE / FROZEN / CANCELLED）详见卡管理概述。
通过 H5 托管页展示时，上述状态校验由 DCS 页面处理，接入机构无需自行判断。

下一步

卡的冻结/解冻、换卡、重置 PIN 等操作见卡管理概述。
引导页的统一字段定义和其他 action 场景见 H5 KYC 与开卡引导页。

关于卡密文回传：DeCard 托管模式不提供把卡密文回传到接入机构后端再自行解密的接口，也没有客户端加解密流程——展示卡敏感信息一律走上述 H5 托管引导页。

​📄 正文

​DeCard 托管模式的唯一机制：H5 托管引导页

​三步流程

​接口（推荐 V2，按 cardId 定位）

​请求参数（卡信息查询场景 action=CARD_INFO）

​响应

​messageDetail 子字段说明

​常见错误响应示例

​前置条件

​下一步