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

# 卡管理 · 概述

> 卡管理组的着陆页：讲清虚拟卡/实体卡两种形态、卡状态机，以及冻结/解冻、查详情等能力如何分两条路径（REST 接口 + 托管引导页）交付。

## 📄 正文

用户完成 KYC 后，您即可为其发卡，并在卡的整个生命周期内对它进行管理——冻结防盗刷、丢卡后注销、收到实体卡后激活、忘记密码后重置 PIN。作为持牌、自有 BIN 的发卡机构，DCS 在底层完成与卡组织、发卡处理器之间的状态同步，您只需关心业务语义：这张卡现在是什么状态、允许做哪些操作。

**每张卡都归属于一个用户**，因此发卡前请确保该用户已存在并通过 KYC（见 [用户管理](../managing-users/overview)）。

本组涵盖发卡、查看卡敏感信息、冻结/解冻、管理 PIN、申请与激活实体卡，以及将卡片添加到 Apple Wallet 或 Google Wallet（Push Provisioning）。

### 虚拟卡与实体卡

卡按形态分为虚拟卡与实体卡，两者的交付与管理流程不同：

* **虚拟卡**：发卡后即时可用，无需邮寄与激活。
* **实体卡**：需邮寄给用户，**收到后必须激活**方可使用；激活与邮寄信息查询见下文。

### 两条能力交付路径（重要）

DeCard 托管的卡管理能力**不是一组对称的独立 REST 接口**，而是分两条路径交付，请勿照搬其他平台的「每个动作一个接口」模型：

| 能力                      | 交付方式        | 入口                                                           |
| :---------------------- | :---------- | :----------------------------------------------------------- |
| 冻结 / 解冻                 | **REST 接口** | `POST /card/v2/block`                                        |
| 查询卡详情 / 状态              | **REST 接口** | `GET /card/v2/detail`                                        |
| 查看卡敏感信息（卡号 / CVV / 有效期） | **托管引导页**   | `/redirect/v2/guidance-link` ⟶ `action=CARD_INFO`            |
| 申请实体卡                   | **托管引导页**   | `/redirect/v2/guidance-link` ⟶ `action=CREATE_PHYSICAL_CARD` |
| 激活实体卡                   | **托管引导页**   | `/redirect/v2/guidance-link` ⟶ `action=ACTIVE_PHYSICAL_CARD` |
| 更新 PIN                  | **托管引导页**   | `/redirect/v2/guidance-link` ⟶ `action=UPDATE_PIN`           |

> 卡敏感信息查询、实体卡申请/激活、PIN 更新等涉及敏感操作的动作，统一通过托管引导页 `/redirect/v2/guidance-link` 按 `action` 枚举完成——用户在 DCS 托管页面内用短信或邮箱验证码完成操作，敏感信息不经接入机构后端。公开 guidance-link 的 `action` 枚举为 `KYC_GUIDE` / `CARD_INFO` / `CREATE_PHYSICAL_CARD` / `ACTIVE_PHYSICAL_CARD` / `UPDATE_PIN` / `TRAVEL_RULE` / `KYC_EXTRA_DOC`。DeCard 托管没有独立的 reset-pin / activate / convert-to-phy / invalidate REST 接口。

## 核心概念：卡状态机

DCS 用卡状态字段表达卡的生命周期阶段，所有管理操作本质上都是在驱动这台状态机。虚拟卡与实体卡各有一套状态枚举。

<Frame>
  <img className="block dark:hidden" src="https://mintcdn.com/dcs-0bf7a937/Oer2uXl_QwfDjoPv/imgs/diagrams/va-card-states-light.svg?fit=max&auto=format&n=Oer2uXl_QwfDjoPv&q=85&s=f13d3985f18770cd0718d78436708395" alt="卡状态机" width="700" height="512" data-path="imgs/diagrams/va-card-states-light.svg" />

  <img className="hidden dark:block" src="https://mintcdn.com/dcs-0bf7a937/Oer2uXl_QwfDjoPv/imgs/diagrams/va-card-states-dark.svg?fit=max&auto=format&n=Oer2uXl_QwfDjoPv&q=85&s=e8b7748cca0eea599fae54ed17722df1" alt="卡状态机" width="700" height="512" data-path="imgs/diagrams/va-card-states-dark.svg" />
</Frame>

**虚拟卡状态（`cardStatus`）**

| 状态                 | 含义          |
| :----------------- | :---------- |
| **NORMAL**（正常）     | 卡片已激活，可正常使用 |
| **FROZEN**（已冻结）    | 卡片被冻结，暂停使用  |
| **CANCELLED**（已销卡） | 卡片被销卡，停止使用  |

**实体卡状态（`physicalCardStatus`）**

| 状态                 | 含义               |
| :----------------- | :--------------- |
| **UN\_APPLY**（未申请） | 尚未申请实体卡          |
| **INACTIVE**（未激活）  | 已申请实体卡，但未激活，无法使用 |
| **ACTIVE**（已激活）    | 卡片已激活，可正常使用      |
| **REPLACE**（换卡）    | 卡片处于换卡流程中        |
| **FROZEN**（已冻结）    | 卡片被冻结，暂停使用       |
| **CANCELLED**（已销卡） | 卡片被销卡，停止使用       |

> **换卡（Replace Card）**：当前公开接口中没有换卡 `action` 或 REST 接口，`REPLACE` 仅作为 `physicalCardStatus` 的一个状态值出现。如需换卡，请联系 DCS 团队确认可用方式。

## 操作一览

每项操作的一句话摘要与入口如下；REST 类操作（冻结/解冻、查详情）在本页下文展开，引导页类操作（查卡密、实体卡申请/激活、PIN）见各自子页。

| 操作          | 谁做   | 摘要                                               | 详见                                               |
| :---------- | :--- | :----------------------------------------------- | :----------------------------------------------- |
| 查询卡详情 / 状态  | 接入机构 | 用 `/card/v2/detail` 查卡状态与余额；`cardId` 传空可查用户名下全部卡 | [本页 · 查询卡详情](#查询卡详情)                             |
| 冻结 / 解冻     | 接入机构 | 用 `/card/v2/block` 切换 `block` 布尔值，冻结防盗刷、解冻恢复使用   | [本页 · 冻结 / 解冻](#冻结-/-解冻)                         |
| 查看卡敏感信息     | 终端用户 | 引导页 `action=CARD_INFO`，在 DCS 托管页内展示完整卡号/CVV/有效期  | [查看卡敏感信息](./viewing-encrypted-card-details)      |
| 申请实体卡       | 终端用户 | 引导页 `action=CREATE_PHYSICAL_CARD`，用户填邮寄信息提交申请    | [申请卡](./issuing-cards)                           |
| 激活实体卡       | 终端用户 | 引导页 `action=ACTIVE_PHYSICAL_CARD`，用户收到卡后激活       | [申请卡](./issuing-cards)                           |
| 重置 / 更新 PIN | 终端用户 | 引导页 `action=UPDATE_PIN`，用户在托管页内设置 PIN，明文不经接入机构   | [管理卡片 PIN](./managing-a-cards-pin)               |
| 添加到数字钱包     | 终端用户 | 调绑卡 API 把卡推送至 Apple / Google Wallet              | [Apple Pay 与 Google Pay 绑卡](./push-provisioning) |

### 查询卡详情

通过 `GET /card/v2/detail` 查询卡详情。该接口的 `cardId` 为非必填：**传值**查询指定单卡、**传空**查询该用户名下的卡列表；响应 `data` 始终为数组。返回卡状态（虚拟卡 `cardStatus` 与实体卡 `physicalCardStatus`，枚举见上方状态机）以及该卡关联的余额信息（`walletBalance` / `caBalance` / `cardBalance` / `balanceCurrency` / `billingCurrency`）。

每张卡关联用户级余额、授权决策在 DCS 内部完成，是 DeCard 托管（独立账户）模式的核心特征。余额管理详见 [用户余额](../managing-transactions/user-balance)。

> 该接口以 `cardId` 精确标识卡片。

### 冻结 / 解冻

通过 `POST /card/v2/block` 冻结或解冻卡——这是同一个接口，用 `block` 布尔值切换方向：`block=true` 冻结、`block=false` 解冻。冻结可在卡片疑似被盗刷或用户主动暂停时立即生效。

| 字段                      | 类型      | 必填    | 说明                       |
| :---------------------- | :------ | :---- | :----------------------- |
| `externalUserId`        | string  | 是     | 用户 ID                    |
| `cardId`                | string  | 是     | 卡 ID                     |
| `block`                 | boolean | 是     | `true` = 冻结；`false` = 解冻 |
| `smsCode` / `emailCode` | string  | 解冻时必填 | 解冻验证码，二选一                |

* **冻结**（`block=true`）通常无需验证码。
* **解冻**（`block=false`）需要验证码：传 `smsCode`（短信）或 `emailCode`（邮箱）**二选一**。

**冻结卡（无需验证码）**

```json theme={null}
{
  "externalUserId": "user_xxxxxxxx",
  "block": true,
  "cardId": "card_xxxxxxxx"
}
```

**解冻卡（需验证码）**

```json theme={null}
{
  "externalUserId": "user_xxxxxxxx",
  "block": false,
  "cardId": "card_xxxxxxxx",
  "smsCode": "<sms-otp>"
}
```

**响应示例**

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

`data` 为布尔值，表示**本次冻结/解冻操作是否成功**：`true` = 成功、`false` = 失败。响应结构 `{code, message, messageDetail, data}` 全站统一，详见 [API 快速开始](../../getting-started/quickstart)。

> `block` 接口只能在 `NORMAL` ⇄ `FROZEN`（或 `ACTIVE` ⇄ `FROZEN`）之间切换。

## 下一步

* [申请卡](./issuing-cards)——为已通过 KYC 的用户申请虚拟卡或实体卡。虚拟卡发卡后即时可用；实体卡需邮寄后激活。
* [查看卡敏感信息](./viewing-encrypted-card-details)——通过托管引导页（action=CARD\_INFO）安全展示完整卡号、CVV 与有效期，敏感信息不经接入机构后端。
* [管理卡片 PIN](./managing-a-cards-pin)——通过托管引导页（action=UPDATE\_PIN）让用户在 DCS 托管页内设置/更新 PIN，接入机构不接触明文或密文 PIN。
* [Apple Pay 与 Google Pay 绑卡](./push-provisioning)——在您的应用内将 DCS 发行的 Visa 卡一键添加到 Apple Wallet 或 Google Wallet，无需在钱包应用中手动输入卡号。