> ## 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.

# 开卡流程

> 为您的客户开卡的端到端接入路径：创建用户档案 → 提交 KYC 工单 → 等待 KYC 通过 → 申请虚拟卡。本页讲清每个阶段调什么接口、DCS 处理什么、预期的状态流转。

## 📄 正文

无论您的用户来自交易所、钱包还是平台应用，您都可以通过 DCS 的开卡接口为其发行虚拟卡，后续可再升级为实体卡。开卡路径在所有场景下一致：先建立用户档案并在 DCS 侧完成 KYC，KYC 通过后再提交虚拟卡申请。

DCS 作为持牌、自有 BIN 的发卡机构，承接发卡、KYC 审核、授权转发、清算与对账；接入机构负责持卡人侧体验，以及自身的额度与风控决策。

## 开卡时序

无论 KYC 资料如何采集，时序都一样：**创建用户 → 申请 KYC（仅在需要文件时先上传）→ 等待 KYC 通过 → 申请虚拟卡**。同一用户后续再开卡时，已有的 `kycTicketId` 可复用，无需重交 KYC 资料。

KYC 资料的采集方式二选一：在**接入机构自有界面**采集并提交给 DCS，或把用户交给 **DCS 托管 H5 页**代为采集。两种方式的审核均由 DCS 的 KYC 服务商执行（见 [KYC 服务商说明](../../customer-success/faq-kyc-vendor)），KYC 通过之后的流程完全一致。

<Frame>
  <img className="block dark:hidden" src="https://mintcdn.com/dcs-0bf7a937/SwaeBNwQm2hgkUz9/imgs/diagrams/pa-card-issuing-light.svg?fit=max&auto=format&n=SwaeBNwQm2hgkUz9&q=85&s=99a1b22c518f4c66072cbeed2afa00b6" alt="开卡端到端流程：从 KYC 到虚拟卡" width="799" height="1052" data-path="imgs/diagrams/pa-card-issuing-light.svg" />

  <img className="hidden dark:block" src="https://mintcdn.com/dcs-0bf7a937/SwaeBNwQm2hgkUz9/imgs/diagrams/pa-card-issuing-dark.svg?fit=max&auto=format&n=SwaeBNwQm2hgkUz9&q=85&s=6a6b58a6e61f3e6c2ba6c6de9dabb06b" alt="开卡端到端流程：从 KYC 到虚拟卡" width="799" height="1052" data-path="imgs/diagrams/pa-card-issuing-dark.svg" />
</Frame>

两条路线的执行细节见 [申请 KYC](../kyc/apply-kyc) 与 [H5 KYC 引导页](../kyc/h5-kyc-guidance)。

> 两条 URL 职责不同：`generate-pre-upload-url` 只签发 S3 文件上传地址；`card-redirect/v1/guidance-link` 签发 DCS 托管 H5 页面。接入机构自有界面收料并直传文件时用前者；需要让终端用户在 DCS 页面完成活体、信息验证、补充开卡资料、KYC 或 KYC 续期时用后者。

## 核心接口：申请虚拟卡

**`POST /open-api/card-order/v1/apply-virtual`**

> 请求与响应字段以 API 参考对应接口页为准。

### 请求参数

| 字段              | 类型     | 必填 | 说明                                                            |
| --------------- | ------ | -- | ------------------------------------------------------------- |
| `profileId`     | string | 必填 | 卡配置 ID（即 [Card Profile](./card-profiles)，联系 DCS 团队获取）。最大长度 50 |
| `cardOrderRef`  | string | 必填 | 卡订单幂等字段，由接入机构生成。最大长度 50                                       |
| `cardApplyMode` | string | 必填 | 值固定为 `NORMAL`。接口层历史遗留的 `COMPLETE` 为存量兼容模式、计划下线，新接入请勿使用        |
| `kycTicketId`   | string | 必填 | KYC 凭证 ID（由「申请 KYC」返回）                                        |
| `customerId`    | string | 必填 | 用户 ID（由「创建用户」返回）                                              |

### 最小请求示例

```json theme={null}
{
  "profileId": "PROFILE_xxx",
  "cardOrderRef": "ord-20260616-0001",
  "cardApplyMode": "NORMAL",
  "customerId": "C100001",
  "kycTicketId": "KYC_1a2b"
}
```

### 响应

统一响应结构为 `{ code, message, messageDetail, data }`：

* `code` / `message`：系统级返回码与文案。
* `messageDetail`：面向终端用户的可展示提示（`title` / `message` / `type` / `action` / `linkUrl` 等），用于在前端引导补件或重试。
* `data`：业务数据，见下表。

<Warning>
  **响应结构一致性**：本套接口以 `code` 表示系统级成功，业务结果另在 `data.status` 中表达；当订单审核被拒时，响应 `code` 仍可能为成功，而 `data.status=FAILED`。接入机构请以 `data.status` 判断开卡业务结果，勿仅凭 `code` 判定开卡成功。统一响应结构与成功 `code` 判定见[鉴权指南](../../integration-resources/authentication)；卡订单失败 `errorCode` 归类见[卡申请错误码](./card-order-codes)。
</Warning>

`data` 字段：

| 字段                          | 说明                                                    |
| --------------------------- | ----------------------------------------------------- |
| `cardOrderId`               | 卡订单 ID（用于查订单详情）                                       |
| `profileId`                 | 卡配置 ID                                                |
| `type`                      | 卡类型：`VIRTUAL` / `VIRTUAL_TO_PHYSICAL` / `REPLACEMENT` |
| `customerId`                | 用户 ID                                                 |
| `cardId`                    | 卡 ID（订单完成后返回；后续所有卡操作均用它）                              |
| `status`                    | 卡订单状态，见下方状态机                                          |
| `errorCode` / `errorReason` | 失败时的错误码与原因                                            |
| `cardOrderRef`              | 回显的幂等字段                                               |
| `needExtraInfo`             | 是否需补充问卷（`type=VIRTUAL` 使用）                            |
| `createTime` / `modifyTime` | 创建 / 最后更新时间，格式 `yyyy-MM-dd'T'HH:mm:ss+08:00`          |

### 虚拟卡订单状态机

<Frame>
  <img className="block dark:hidden" src="https://mintcdn.com/dcs-0bf7a937/oUoeUKtwWWK2o-Li/imgs/diagrams/pa-card-order-states-light.svg?fit=max&auto=format&n=oUoeUKtwWWK2o-Li&q=85&s=29ac3aac4e7ce6fce112c4354804fdc8" alt="虚拟卡订单状态机" width="742" height="390" data-path="imgs/diagrams/pa-card-order-states-light.svg" />

  <img className="hidden dark:block" src="https://mintcdn.com/dcs-0bf7a937/oUoeUKtwWWK2o-Li/imgs/diagrams/pa-card-order-states-dark.svg?fit=max&auto=format&n=oUoeUKtwWWK2o-Li&q=85&s=349607bcf95a332a07cfa8779c1f38f1" alt="虚拟卡订单状态机" width="742" height="390" data-path="imgs/diagrams/pa-card-order-states-dark.svg" />
</Frame>

| status                  | 含义                                                     |
| ----------------------- | ------------------------------------------------------ |
| `PENDING`               | 申请已受理，排队处理中                                            |
| `CUSTOMER_PASS`         | 用户档案校验通过                                               |
| `KYC_PASS`              | KYC 审核通过                                               |
| `CHANNEL_CUSTOMER_PASS` | 发卡渠道已受理持卡人，卡片创建中                                       |
| `COMPLETED`             | 开卡完成，返回 `cardId`，卡片即刻可用                                |
| `FAILED`                | 申请失败，可发生在任一阶段；读 `errorCode` / `errorReason` 决定重试还是补交资料 |

订单进入 `COMPLETED` 后，`data.cardId` 即可用；**虚拟卡无需激活，开卡完成即为可用状态**。

> 注：本接口的成功态枚举为 `COMPLETED`。

## 需要补充信息时

DCS 在审核过程中可能要求持卡人补充信息才能通过申请。此时开卡申请返回 `needExtraInfo = true`：申请停留在进行中，补充完成前不会进入 `COMPLETED`。

补充信息**没有独立的 open-api 提交接口**：持卡人须在 H5 引导页（`guidance-link` `type=6`）完成补充开卡资料。当审核判定需持卡人补充 KYC 信息时，DCS 会自动创建一张 **KYC 补充信息工单**，从创建到通过/拒绝全程跟踪该请求——工单不由接入机构创建。

1. **感知请求**：卡订单的 `needExtraInfo` 变为 `true`，同时收到 `KYC_EXTRA_INFO_TICKET` Webhook，工单状态为 `INIT`。
2. **引导用户提交**：调 `POST /open-api/card-redirect/v1/guidance-link`，传 `type=6` 与 `cardOrderId` 换取 H5 链接，打开给用户。
3. **跟踪结果**：用户提交后工单进入 `PENDING`，随后进入 `PASSED`（卡订单继续推进）或 `REJECTED`（Webhook 携带 `rejectReason` 与 `rejectRemark`）。
4. **随时查询**：`GET /open-api/kyc-extra-info-ticket/v1/list` 返回该卡的工单列表、状态与拒绝原因。

| 状态         | 说明         | 是否终态 | 接入机构动作                                                  |
| ---------- | ---------- | ---- | ------------------------------------------------------- |
| `INIT`     | 工单已创建，等待用户 | 否    | 引导用户到 H5 页提交信息                                          |
| `PENDING`  | 已提交，审核中    | 否    | 等待审核结果                                                  |
| `PASSED`   | 已通过        | 是    | 卡订单继续推进，无需动作                                            |
| `REJECTED` | 被拒或关闭      | 是    | 读 `rejectReason` / `rejectRemark`；审核方再次要求补充时，DCS 会创建新工单 |

查询时按 `cardOrderId` 返回该订单的全部工单（最新在前），含历史工单的拒绝原因；传 `kycExtraInfoTicketId`（来自 Webhook）可只查某一张工单。

<Warning>
  一个卡订单可能先后有多张工单——被拒后审核方再次发起会创建新的一张，但同一时间仅有一张在途。`rejectReason` 与 `rejectRemark` 仅在 `REJECTED` 状态有值，其余状态为空字符串。
</Warning>

## 拿到卡之后

1. 用 `cardOrderId` 调 `GET /open-api/card-order/v1/detail` 轮询状态（响应字段见上方「响应」表），或等待卡订单状态的 Webhook 通知；状态为 `COMPLETED` 后取 `cardId`。
2. 用 `cardId` 调 [查卡详情](./virtual-card) 获取 `panFirst6` / `panLast4` 等非敏感信息。
3. 需展示完整卡号 / CVV 时：PCI 持牌接入机构用 [获取卡敏感信息](./secure-card)；非 PCI 接入机构走托管页（guidance link），敏感信息直接在终端用户前端展示、不经过接入机构后端。
4. 需要实体卡时，调虚拟卡转实体卡接口（参见 [实体卡](./physical-card)）。
5. 若订单返回 `needExtraInfo`，先按上文「需要补充信息时」一节处理完补充请求。

## 下一步

* 实体卡的申请、寄送与激活：见 [实体卡](./physical-card)。
* 冻结、解冻、注销、重置 PIN 等日常卡操作：见 [卡管理](./card-management)。
* 卡订单状态码与失败 `errorCode` 归类（含可否重试 / 怎么办 / 能否补件）：见 [卡申请错误码](./card-order-codes)。