> ## 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 DSS 白名单合作伙伴调用 retrieve-secure-card 获取 encryptedPan / encryptedCvv2 / encryptedExpireDate并按 AES-GCM 约定在自有前端解密展示；附持卡人数据保护要求，以及为独立余额卡开通收款账号（open-va）。

## 📄 正文

卡的完整卡号（PAN）、CVV2 与有效期属于敏感认证数据，常规卡查询接口只返回 `panFirst6` / `panLast4`（见[申请虚拟卡](./applying-virtual-cards)中的单卡查询）。要向持卡人展示完整卡面信息，持有 PCI DSS 的合作伙伴调用本页的 `retrieve-secure-card` 取密文自行解密展示；无 PCI DSS 的合作伙伴可集成 DCS 平台卡信息安全托管页。本页同时收录独立余额卡的收款账号开通接口 `open-va`。

## 获取卡敏感信息

```http theme={null}
POST /open-api-corp/card/v1/retrieve-secure-card
```

返回密文级 PAN / CVV2 / 有效期，供在前端安全展示。

<Warning>
  **仅限持有 PCI DSS 的合作伙伴可调**（否则返回 `PCI_NOT_CERTIFIED`）；无 PCI DSS 的合作伙伴可集成平台卡信息安全托管页。
</Warning>

### 请求参数

| 字段       | 类型     | 必填 | 说明                        |
| -------- | ------ | -- | ------------------------- |
| `cardId` | String | 是  | ≤20；卡 ID；须属本合作伙伴且为 ACTIVE |

### 响应 data

| 字段                    | 类型     | 说明                  |
| --------------------- | ------ | ------------------- |
| `cardId`              | String | 卡 ID                |
| `encryptedPan`        | String | 卡号（AES-GCM 密文）      |
| `encryptedCvv2`       | String | CVV2（密文）            |
| `encryptedExpireDate` | String | 有效期（密文，原文 mm/yy）    |
| `iv`                  | String | 本次随机 IV（Base64），解密用 |

### 解密约定

* 算法：**AES/GCM/NoPadding**，128 位（128-bit）认证标签。
* 密钥：即您的 **SK**。
* IV：`encryptedPan` / `encryptedCvv2` / `encryptedExpireDate` 三个密文字段**共用同一个 `iv`**（每次调用随机生成，Base64 编码返回）。

<Warning>
  **CVV2 与有效期实时获取、不可缓存**——每次需要展示时重新调用本接口取密文解密。
</Warning>

### 请求与响应示例

```json theme={null}
{
  "cardId": "5185740066240790530"
}
```

```json theme={null}
{
  "code": "SYS_SUCCESS",
  "message": null,
  "data": {
    "cardId": "5185740066240790530",
    "encryptedPan": "UGFuTW9ja0NpcGhlclRleHRCYXNlNjQrVGFnMTZC",
    "encryptedCvv2": "Q3Z2Mk1vY2tDaXBoZXJUZXh0K1RhZzE2Qg==",
    "encryptedExpireDate": "RXhwTW9ja0NpcGhlclRleHQrVGFnMTZC",
    "iv": "MTIzNDU2Nzg5MGFi"
  }
}
```

### 错误码

| 错误码                 | 说明                        |
| ------------------- | ------------------------- |
| `PCI_NOT_CERTIFIED` | 未开通卡敏感信息访问权限（不在 PCI 白名单）  |
| `CARD_INVALID`      | 卡不存在 / 不属本合作伙伴 / 非 ACTIVE |

## PCI DSS · 持卡人数据保护

按 PCI DSS 要求，完整卡号（PAN）、CVV2 与有效期属于敏感认证数据，须全程按最小暴露原则处理：

* **掩码默认**：默认情况下，前端仅展示掩码卡号——保留前 6 位与后 4 位（如 531993 •••• •••• 8888），CVV2 与有效期不作默认展示。
* **按需临时展示**：仅当业务确有需要且完成持卡人身份核验后，方可临时解密并在前端展示明文。
* **明文不落地**：展示过程中不得将明文以任何形式落地存储——数据库、文件、日志、缓存、埋点与链路追踪等均不得留存；CVV2 在授权后亦不得保存。
* **密钥进 KMS**：用于解密的密钥须托管于密钥管理服务（KMS）并定期轮换。

## 为独立余额卡开通收款账号

```http theme={null}
POST /open-api-corp/card/v1/open-va
```

为独立余额卡按币种开通充值账号（VA）；合作伙伴可按需选择银行转账入金或公司资金池调拨为卡充值（充值与对账见[资金与对账](./funding-and-reconciliation)）。

### 请求参数

| 字段                  | 类型              | 必填 | 说明                                                                                                                                              |
| ------------------- | --------------- | -- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `cardId`            | String          | 是  | ≤32；卡 ID；须属本合作伙伴、且为独立余额卡                                                                                                                        |
| `fundingCurrencies` | `Array<String>` | 是  | 待开通 VA 的币种列表（至少一个，取值 `USD` / `HKD`；各申一个 VA）；元素不可空、币种不可重复，空/重复/非枚举 → `DAPI_PARAM_INVALID`；还须为本企业允许币种的子集，超出范围整单拒绝（不做部分开通）→ `CURRENCY_NOT_ALLOWED` |

### 响应

动作类接口，`data` 为 `null`。开通后的收款账号请调[获取充值入金信息](./deposits)按 `subjectType=CARD` 查询——开 VA 与查账号分属两个接口，本接口只负责开通。

### 请求与响应示例

```json theme={null}
{
  "cardId": "5185740066240790531",
  "fundingCurrencies": ["USD", "HKD"]
}
```

```json theme={null}
{
  "code": "SYS_SUCCESS",
  "message": null,
  "data": null
}
```

### 错误码

| 错误码                    | 说明                                                         |
| ---------------------- | ---------------------------------------------------------- |
| `CARD_INVALID`         | 卡不存在 / 不属本合作伙伴                                             |
| `CARD_NOT_DEDICATED`   | 非独立余额卡，不可开 VA                                              |
| `UNSUPPORTED_CURRENCY` | 币种不支持（仅 `USD` / `HKD`）                                     |
| `CURRENCY_NOT_ALLOWED` | 申请币种不在该企业允许的币种列表内（message 点名具体币种）                          |
| `SUBJECT_INVALID`      | 卡账本主体（account\_holder）缺失，或持卡人 KYB/KYC 户名缺失（均属主体侧问题，无法开 VA） |

## 下一步

* 给独立余额卡入金、公司资金池调拨与对账：[资金与对账](./funding-and-reconciliation)
* 把已激活的虚拟卡同号升级为实体卡：[实体卡](./physical-cards)