> ## 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 实体卡——一张可在全球线下商户、ATM 与数字钱包中使用的 Visa 卡。实体卡与虚拟卡共享同一套开卡、KYC、授权与清算流程，区别只在于其有形载体、寄送环节与激活步骤。

实体卡是有形的支付工具，内嵌 EMV 芯片与非接触（NFC）技术，印有卡号、有效期与卡片识别信息，可在超过 99% 的线下受理点使用。卡面支持品牌定制（如压花名字、企业卡面编码），帮助您向持卡人传递品牌形象。

## 实体卡与虚拟卡

| 维度   | 实体卡                       | 虚拟卡                               |
| :--- | :------------------------ | :-------------------------------- |
| 存在形式 | 有形卡片（塑料 / 金属）             | 仅数字信息                             |
| 主要场景 | 线下 POS、ATM 取现、差旅          | 线上购物、订阅、数字广告                      |
| 获取方式 | 申请后寄送，需激活                 | 在线即时发放，自动激活                       |
| 数字钱包 | 支持 Apple Pay 与 Google Pay | 支持（详见[推送绑卡](./push-provisioning)） |
| 适用建议 | 与虚拟卡互补，按场景组合使用            | —                                 |

> 实体卡与虚拟卡是互补而非替代关系。建议您让终端用户用虚拟卡覆盖线上支付与订阅、用实体卡覆盖线下消费与差旅。

## 如何为用户发行实体卡

DCS 实体卡通过**虚拟卡换实体卡**订单产生：先有一张虚拟卡，再针对该卡发起换卡订单，附上寄送地址与卡面信息。

<Frame>
  <img className="block dark:hidden" src="https://mintcdn.com/dcs-0bf7a937/oUoeUKtwWWK2o-Li/imgs/diagrams/pa-physical-issue-light.svg?fit=max&auto=format&n=oUoeUKtwWWK2o-Li&q=85&s=bd25655be76f1788cc6f2042ed4da70c" alt="虚拟卡转实体卡申请时序图" width="638" height="610" data-path="imgs/diagrams/pa-physical-issue-light.svg" />

  <img className="hidden dark:block" src="https://mintcdn.com/dcs-0bf7a937/oUoeUKtwWWK2o-Li/imgs/diagrams/pa-physical-issue-dark.svg?fit=max&auto=format&n=oUoeUKtwWWK2o-Li&q=85&s=3b02f4e29ba36d7c6015c10200815088" alt="虚拟卡转实体卡申请时序图" width="638" height="610" data-path="imgs/diagrams/pa-physical-issue-dark.svg" />
</Frame>

**接口**：`POST /open-api/card-order/v1/virtual-to-physical`（谁做：接入机构发起）

最小请求体：

```json theme={null}
{
  "cardOrderRef": "your-idempotent-ref",
  "replaceCardId": "被替换的虚拟卡 cardId",
  "virtualToPhysicalInfo": {
    "countryCode": "SG",
    "state": "Singapore",
    "city": "Singapore",
    "postalCode": "049315",
    "address": "1 Raffles Place",
    "embossingName": "TOM LEE",
    "cardLayoutCode": "ABC123",
    "needShippingInfo": true
  }
}
```

请求字段（节选，完整约束见 API 参考）：

| 字段                                            | 类型      | 必填 | 说明                          |
| :-------------------------------------------- | :------ | :- | :-------------------------- |
| `cardOrderRef`                                | string  | 是  | 卡订单幂等字段，最大长度 50             |
| `replaceCardId`                               | string  | 是  | 被替换的虚拟卡 cardId，最大长度 50      |
| `virtualToPhysicalInfo.countryCode`           | string  | 是  | 收件国家码，2 位 ISO（如 SG/US/CN）   |
| `virtualToPhysicalInfo.state`                 | string  | 是  | 省/州，最大长度 20                 |
| `virtualToPhysicalInfo.city`                  | string  | 是  | 市，最大长度 20                   |
| `virtualToPhysicalInfo.postalCode`            | string  | 是  | 邮编，最大长度 10                  |
| `virtualToPhysicalInfo.address`               | string  | 是  | 地址，最大长度 40                  |
| `virtualToPhysicalInfo.address2` / `address3` | string  | 否  | 地址补充行，各最大长度 40              |
| `virtualToPhysicalInfo.embossingName`         | string  | 是  | 卡面压花名字，最大长度 26              |
| `virtualToPhysicalInfo.cardLayoutCode`        | string  | 是  | 卡面编码，最大长度 6（由 DCS 在卡配置阶段提供） |
| `virtualToPhysicalInfo.needShippingInfo`      | boolean | 是  | 是否需要 DCS 代为寄送               |
| `virtualToPhysicalInfo.mailMobileCode`        | string  | 否  | 邮寄联系手机号国家码（2 位 ISO，如 SG）    |
| `virtualToPhysicalInfo.mailMobile`            | string  | 否  | 邮寄联系手机号（如 91159519）         |

> 24 小时内虚拟卡转实体卡有次数上限，超限返回 `DAPI_VIRTUAL_TO_PHYSICAL_APPLY_LIMIT_EXCEEDED`，需退避后重试。

> 寄送地址建议仅使用拉丁字符、数字与基本标点。非拉丁字符（中文、阿拉伯文等）可能无法通过制卡或物流地址校验，请在提交前转写为拉丁拼写。

成功响应返回一笔卡订单，关键字段：

| 字段                          | 说明                                                               |
| :-------------------------- | :--------------------------------------------------------------- |
| `cardOrderId`               | 卡订单 ID                                                           |
| `type`                      | 订单类型，此处为 `VIRTUAL_TO_PHYSICAL`                                   |
| `cardId`                    | 卡 ID                                                             |
| `replaceCardId`             | 被替换的虚拟卡 cardId                                                   |
| `status`                    | 订单状态：`PENDING / PHYSICAL_SETTING_COMPLETED / COMPLETED / FAILED` |
| `errorCode` / `errorReason` | 失败时的错误码与原因                                                       |

> **订单成功终态**：卡订单成功终态为 `COMPLETED`，可辅以 `cardId` 是否有值作为判据。其中 `PHYSICAL_SETTING_COMPLETED` 是虚转实流程的中间过程态、非终态（终态为 `COMPLETED` / `FAILED`）。
>
> 所有接口返回统一结构 `{ code, message, messageDetail, data }`，其字段含义与成功 code/错误码字典见[鉴权指南](../../integration-resources/authentication)。实体卡寄送时效与费用以与 DCS 约定的卡配置为准，相关字段当前不随接口响应或 Webhook 返回。

### ⚠️ 新旧两张卡的关系（必读）

虚转实完成后，同一位持卡人名下会同时存在**两个 cardId**。这一段决定了您在激活前后该用哪个 `cardId`、以及授权该记在哪张卡上：

|             | 说明                                                           |
| :---------- | :----------------------------------------------------------- |
| **cardId**  | 实体卡是一个**新的 `cardId`**，与原虚拟卡不同。请把它单独保存                        |
| **卡号（PAN）** | 实体卡与原虚拟卡的**卡号相同**——不是换号，只是多了一张实体载体                           |
| **激活前**     | 实体卡处于 `PENDING_ACTIVATION` **不可用**；原虚拟卡仍可正常消费，**所有授权仍归原虚拟卡** |
| **激活后**     | 原虚拟卡会**被自动注销**（`INVALID`），此后所有授权归实体卡                         |

因此：激活是一个**切换点**。请在收到激活成功后，把后续查询、冻结、限额等操作的 `cardId` 从虚拟卡切到实体卡；同时注意原虚拟卡转为 `INVALID` 属于预期行为，不是异常。

## 如何激活实体卡

实体卡寄达后需**激活**才能使用，虚拟卡则自动激活无需此步。

<Frame>
  <img className="block dark:hidden" src="https://mintcdn.com/dcs-0bf7a937/oUoeUKtwWWK2o-Li/imgs/diagrams/pa-physical-activate-light.svg?fit=max&auto=format&n=oUoeUKtwWWK2o-Li&q=85&s=ef1cabb40526c3d9530eab56e7562891" alt="实体卡激活时序图" width="476" height="318" data-path="imgs/diagrams/pa-physical-activate-light.svg" />

  <img className="hidden dark:block" src="https://mintcdn.com/dcs-0bf7a937/oUoeUKtwWWK2o-Li/imgs/diagrams/pa-physical-activate-dark.svg?fit=max&auto=format&n=oUoeUKtwWWK2o-Li&q=85&s=3f2ce2726052f5150876998b7800e3b2" alt="实体卡激活时序图" width="476" height="318" data-path="imgs/diagrams/pa-physical-activate-dark.svg" />
</Frame>

**接口**：`POST /open-api/card/v1/physical-active`（谁做：接入机构在持卡人收到卡后发起）

请求体：

```json theme={null}
{
  "cardId": "实体卡 cardId"
}
```

| 字段       | 类型     | 必填 | 说明           |
| :------- | :----- | :- | :----------- |
| `cardId` | string | 是  | 卡 ID，最大长度 50 |

成功后卡 `status` 由 `PENDING_ACTIVATION` 变为 `ACTIVATED`，响应 `data` 同时返回 `type`（`PHYSICAL`）、`panFirst6`、`panLast4` 等。卡状态流转与冻结/解冻/换卡详见 [卡管理](./card-management)。

## 下一步

实体卡发行成功后，请前往 [卡管理](./card-management) 了解冻结/解冻、PIN 与换卡操作；如需把实体卡推送至 Apple Pay 与 Google Pay，请参阅 [推送绑卡](./push-provisioning)。