> ## 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）。

## 📄 正文

发卡永远从虚拟卡开始：申请通过即可用；需要实体卡时对已激活的虚拟卡同号升级。本页按「申请 → 查询 → 展示卡号 → 升级实体卡」的顺序讲清每个接口的关键参数与前置条件。

## 申请虚拟卡

`POST /open-api-corp/card/v1/apply`——受理返回 `cardApplyId`，风控与建卡全程异步，终态经 Webhook `CARD_CREATED` / `CARD_REJECTED` 通知（兜底 `GET /card/v1/query-apply`）。

| 字段                          | 必填         | 说明                                                                                                     |
| --------------------------- | ---------- | ------------------------------------------------------------------------------------------------------ |
| `cardApplyRef`              | 是          | ≤64；合作伙伴侧申请唯一标识（幂等键）                                                                                   |
| `subjectType` + `subjectId` | 是          | `ORGANIZATION`→`organizationId` / `CUSTOMER`→`customerId`；主体须 ACTIVE                                   |
| `cardProfileId`             | 是          | 四种卡型之一（与 subjectType 须匹配），见[概述 · 卡片类型](../getting-started/overview)                                    |
| `custodianCustomerId`       | 公司卡必填      | 托管人：本公司某 ACTIVE 员工的 `customerId`                                                                       |
| `ruleIds`                   | SHARED 卡必填 | ≤5 条限额规则，开卡时同步绑定；规则须存在、属同一公司、ACTIVE，金额限额币种须与卡核销币种有交集；**数组内不得重复（不会静默去重）**；任一条不满足即整单拒绝、不产生 `cardApplyId` |

<Note>
  常见拒绝：`CARD_RULE_REQUIRED`（SHARED 卡没带规则，传空数组同样算没带）、`CARD_RULE_DUPLICATE`（重复携带同一条规则）、`CARD_LIMIT_EXCEEDED`（超开卡上限，活卡与在途申请合并计数）、`SUBJECT_INVALID`（公司卡托管人缺失或非本公司有效员工）。
</Note>

查询卡申请：`GET /card/v1/query-apply?cardApplyId=...`——`status=SUCCEED` 时返回 `cardId`；`REJECTED` 时 `errorCode` 固定为 `CARD_RISK_REJECTED`（不透传内部风控码）。

## 查询卡与卡列表

* **单卡**：`GET /open-api-corp/card/v1/query?cardId=...`，返回 `panFirst6` / `panLast4`（不返回完整卡号）、所属公司、持卡主体、`cardProfileId`、卡组织 `cardNetwork`（VISA / MASTERCARD / UPI）、卡币种 `cardCurrency` 与状态。
* **列表**：`GET /open-api-corp/card/v1/list`，可按 `organizationId` / `subjectType` / `subjectId` / `status` 过滤，`page` / `pageSize` 分页。

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

`POST /open-api-corp/card/v1/open-va`——为独立余额卡按币种开通银行虚拟账号（VA）供入金：传 `cardId` + `fundingCurrencies`（USD / HKD，可多个），响应 `data` 为 `null`——开通后的收款账号请调[获取充值入金信息](./deposits)。花公司资金池的卡不可开 VA（`CARD_NOT_DEDICATED`）。独立余额卡也可不开 VA、改由公司资金池划拨充值，见[资金与对账](./funding-and-reconciliation)。

## 获取卡敏感信息

`POST /open-api-corp/card/v1/retrieve-secure-card`——返回密文级 `encryptedPan` / `encryptedCvv2` / `encryptedExpireDate` 与本次随机 `iv`，供在自有前端解密展示。**仅限 PCI DSS 白名单合作伙伴调用**（否则 `PCI_NOT_CERTIFIED`）；无 PCI DSS 的合作伙伴集成 DCS 卡信息安全托管页。

<Warning>
  **解密约定**：AES/GCM/NoPadding、128 位标签，密钥即您的 SK，三个字段共用同一 `iv`。**CVV2 与有效期实时获取、不可缓存**；明文不得以任何形式落地存储（数据库、文件、日志、缓存、埋点与链路追踪均不得留存），前端默认展示掩码卡号（前 6 后 4）。
</Warning>

## 虚拟卡转实体卡

四步链路：**升级申请 → 查物流 → 激活 → 设 PIN**。步骤详见[实体卡](./physical-cards)，卡状态见[状态机与冻结体系](../basic-concepts/states-and-freezing)。

**① 升级申请**：`POST /open-api-corp/card/v1/virtual-to-physical`——传 `cardApplyRef`（幂等键）、`cardId`（须为 ACTIVE 虚拟卡）、`cardLayoutCode`（卡面 code，取值由 DCS 按合作伙伴配置下发）、`embossingName`（≤26，卡面刻印第一行）与可选 `embossingName2`。寄送地址从持卡人 / 托管人名下读取并**锁定为快照**——地址未维护返回 `SHIPPING_ADDRESS_REQUIRED`，同卡已有在途申请返回 `CARD_CONVERT_IN_PROGRESS`。

**② 查物流**：`GET /open-api-corp/card/v1/shipping-info`——返回 `trackingNumber` / `trackingCompanyName`（未寄出为 null）；寄出时推送 Webhook `CARD_SHIPPED`。

**③ 激活**：`POST /open-api-corp/card/v1/activate`——前置是已寄出（否则 `CARD_NOT_SHIPPED`），本接口幂等；成功推送 `CARD_ACTIVATED`。

**④ 设 PIN**：`POST /open-api-corp/card/v1/set-pin`——前置是已激活。PIN 与核身字段（`encryptedPin` / `encryptedCvv2` / `encryptedExpireDate` / `encryptedPanLast4`）由您用 SK 做 AES-GCM 加密后上送，四个密文共用同一 `iv`，与 retrieve-secure-card 同一套加解密约定、方向相反。PIN 明文须 4 位数字、禁连续、禁全同（`PIN_RULE_VIOLATION`）。

## 关联 Webhook

`CARD_CREATED` / `CARD_REJECTED` / 卡状态变更通知 / `CARD_SHIPPED` / `CARD_ACTIVATED`。

## 下一步

* SHARED 卡开卡前先建限额规则：[设置消费限额](./spend-limits)
* 给独立余额卡充值或划拨：[资金与对账](./funding-and-reconciliation)
* 本组详页：[申请虚拟卡](./applying-virtual-cards) · [查看卡敏感信息](./secure-card-details) · [实体卡](./physical-cards)