> ## 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.
# 虚拟卡
> 说明如何申请虚拟卡、查询申请状态，以及开卡成功后如何获取卡片信息。
## 虚拟卡
无论您面向哪个市场、服务哪类终端用户，都可以在数秒内为其签发一张可立即消费的虚拟卡，无需等待制卡与邮寄。DCS 作为持牌发卡机构、自有 BIN Sponsor，在合作伙伴自管模式下为接入机构提供合规、可控的发卡能力——额度由接入机构掌握，授权由接入机构决策，DCS 负责卡的签发、生命周期与卡组织结算。
虚拟卡（Virtual Card）是一种无实体介质的数字化支付卡，具备与实体卡一致的消费授权与状态管理能力，适配线上支付、订阅、跨境结算等场景，是接入机构与终端用户之间的核心资金载体。
***
## 为什么选择虚拟卡
| 特性 | 说明 |
| ------------ | ----------------------------------------------------------- |
| **即时可用** | 无制卡与邮寄环节，申请成功即生成卡，**默认处于激活状态**，可立即用于消费授权。 |
| **敏感信息加密下发** | 卡号、CVV、过期时间等敏感信息只能通过加密接口领取，并直接在前端向终端用户展示，不经接入机构后端落地，降低泄露风险。 |
| **全生命周期可控** | 支持冻结、解冻、注销、换卡等操作，接入机构凭 `cardId` 实时控制卡片权限，应对挂失、账户异常等场景。 |
| **可升级实体卡** | 虚拟卡可在后续申请转为实体卡，卡号保持一致（详见下文）。 |
***
## 虚拟卡的创建流程
虚拟卡的签发以**卡订单（Card Order）**为驱动，整个流程**异步执行**：您提交一次申请请求，DCS 返回 `cardOrderId`，随后通过查询接口或 Webhook 跟踪状态直至终态。
| 角色 | 职责 |
| -------- | ------------------------------------ |
| **接入机构** | 收集用户资料、发起申请、跟踪状态、领取敏感信息、向终端用户展示与管理卡片 |
| **DCS** | 创建客户档案、执行 KYC、向卡组织渠道发卡、回调状态、管理卡组织结算 |
> 申请所需的前置条件（企业 Enterprise、卡配置 Card Profile）、完整请求字段与卡订单状态都集中在 [申请卡](./card-issuing) 一页，本页不再重复。
***
## 申请虚拟卡（速览）
**`POST /open-api/card-order/v1/apply-virtual`**
最小必填字段：
| 字段 | 类型 | 必填 | 说明 |
| --------------- | ------ | -- | --------------------------- |
| `profileId` | string | 是 | 卡配置 ID，联系 DCS 团队获取（最大长度 50） |
| `cardOrderRef` | string | 是 | 卡订单幂等字段（最大长度 50） |
| `cardApplyMode` | string | 是 | 值固定为 `NORMAL` |
| `kycTicketId` | string | 是 | KYC 凭证 ID（由「申请 KYC」返回） |
| `customerId` | string | 是 | 用户 ID（由「创建用户」返回） |
调用前请先完成 [申请 KYC](../kyc/apply-kyc) 拿到 `kycTicketId`，再以 `kycTicketId` + `customerId` 发卡。
成功响应返回卡订单的关键信息：
```json theme={null}
{
"code": "SYS_SUCCESS",
"message": "success",
"data": {
"cardOrderId": "CO_xxxxxxxx",
"profileId": "PF_xxxx",
"type": "VIRTUAL",
"customerId": "CU_xxxx",
"cardId": "CARD_xxxx",
"status": "PENDING",
"needExtraInfo": false,
"createTime": "2025-01-01T12:00:00+08:00",
"modifyTime": "2025-01-01T12:00:00+08:00"
}
}
```
**关于统一响应结构**：所有接口都包裹在 `{ code, message, messageDetail, data }` 中——`code` 为系统级返回码（如 `SYS_SUCCESS`），`message` 为简要说明，`messageDetail` 为可直接面向终端用户展示的结构化文案（含 `title`/`type`/`action`/`linkUrl` 等），业务数据在 `data` 内。
> 申请请求需携带的鉴权头与 `Content-Type`、以及 `code` 取值字典，统一以 [鉴权指南](../../integration-resources/authentication) 一页为准。
完整字段表、加密细节与 `needExtraInfo`（KYC 补充信息）的处理动作，请见 [开卡流程](./card-issuing)。
***
## 卡订单状态（虚拟卡）
| 状态 | 含义 | 是否终态 |
| ----------------------- | ------------ | ---- |
| `PENDING` | 初始状态 | 否 |
| `CUSTOMER_PASS` | 系统内部成功创建客户档案 | 否 |
| `KYC_PASS` | KYC 身份验证通过 | 否 |
| `CHANNEL_CUSTOMER_PASS` | 渠道侧客户创建成功 | 否 |
| `COMPLETED` | 虚拟卡成功创建并激活 | 是 |
| `FAILED` | 任一环节失败导致的终态 | 是 |
当状态为 `FAILED`，响应与 `CARD_ORDER` Webhook 中会带 `errorCode` 与 `errorReason`。错误码归类与「可否重试 / 用户怎么办 / 能否补件」请见 [卡申请错误码](./card-order-codes)。
> 状态跟踪可调用 **`GET /open-api/card-order/v1/detail`** 查询，或订阅 `CARD_ORDER` Webhook 被动接收。
***
## 虚拟卡转实体卡
虚拟卡可在后续申请转为实体卡。**关键约定**：
* 转换成功后会生成一个不同于原虚拟卡的 `cardId`，但**两张卡的卡号保持一致**。
* 实体卡激活前，所有授权仍归属原虚拟卡；
* 实体卡激活后，原虚拟卡被注销，授权转归实体卡。
具体步骤见 [实体卡](./physical-card)。
***
## 领取卡敏感信息
虚拟卡的卡号、CVV、过期时间属于敏感信息，须通过加密接口**领取**，并直接在前端向终端用户展示——
* **持 PCI 资质的接入机构**：调用 `retrieve-secure-card` 获取加密卡信息，自行解密后向用户展示；
* **无 PCI 资质的接入机构**：通过托管引导页在 DCS 页面向用户展示，敏感数据不经接入机构系统。
详见 [领取卡敏感信息](./secure-card)。
***
## 下一步
* 准备好前置条件后，前往 [申请卡](./card-issuing) 查看完整字段与申请模式。
* 卡片签发后，前往 [卡管理](./card-management) 了解冻结、解冻、注销与换卡。
* 需要限制单笔/周期消费，请见 [消费限额](./velocity-limits)。