> ## Documentation Index
> Fetch the complete documentation index at: https://developers.uqpay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 签发虚拟卡

> 通过 API 创建虚拟卡，并向持卡人下发卡片凭证。

虚拟卡即时创建，可以立即用于线上交易 —— 无需激活。每张虚拟卡都包含 PAN、过期日期和 CVV。

<Info>
  **前置条件**

  * 一位 `cardholder_status` 为 `SUCCESS` 的持卡人 —— 参见 [创建持卡人](/zh/card-issuance/v1.6/guide/create-and-manage-cardholders)
  * 如果使用 Single mode 产品，发卡账户余额需充足 —— 参见 [为发卡账户余额充值](/zh/card-issuance/v1.6/guide/fund-your-issuing-balance)
</Info>

<h2 id="step-1-select-a-card-product">步骤1：选择卡产品</h2>

列出你账户下可用的卡产品，找一个 `card_form` 包含 `VIR` 的产品。

```bash theme={null}
curl "https://api-sandbox.uqpaytech.com/api/v1/issuing/products?page_number=1&page_size=10" \
  -H "x-auth-token: YOUR_API_TOKEN" \
  -H "Content-Type: application/json"
```

```json theme={null}
{
  "total_items": 2,
  "total_pages": 1,
  "data": [
    {
      "product_id": "467e993f-317a-49fc-9ea0-bf49de7d1f76",
      "card_bin": "40963608",
      "card_scheme": "VISA",
      "mode_type": "SHARE",
      "card_form": ["VIR", "PHY"],
      "card_currency": ["USD", "SGD"],
      "product_status": "ENABLED"
    }
  ]
}
```

保存你要使用的产品的 `product_id`。

<Tip>
  使用 [Simulator](/zh/card-issuance/v1.6/api-reference/simulate-authorization) 测试时，选择 BIN 为 `40963608` 的产品。
</Tip>

<h2 id="step-2-create-the-card">步骤2：创建卡片</h2>

调用 [Create Card](/zh/card-issuance/v1.6/api-reference/create-card) 接口，传入持卡人 ID、产品 ID、币种和卡限额。

```bash theme={null}
curl -X POST https://api-sandbox.uqpaytech.com/api/v1/issuing/cards \
  -H "x-auth-token: YOUR_API_TOKEN" \
  -H "x-idempotency-key: $(uuidgen | tr '[:upper:]' '[:lower:]')" \
  -H "Content-Type: application/json" \
  -d '{
    "cardholder_id": "25ea804d-7fd5-43d5-8792-0fc0214cdb2f",
    "card_product_id": "467e993f-317a-49fc-9ea0-bf49de7d1f76",
    "card_currency": "USD",
    "card_limit": 1000
  }'
```

**响应：**

```json theme={null}
{
  "card_id": "50418faa-57a8-4ce2-9157-621b00b13a3b",
  "card_order_id": "79224316-ecad-4e61-9eeb-e7929bda124c",
  "card_status": "PENDING",
  "order_status": "PROCESSING",
  "create_time": "2026-04-10T18:04:44+08:00"
}
```

卡片初始状态为 `PENDING`，几秒后变为 `ACTIVE`。

<h3 id="optional-parameters">可选参数</h3>

| 参数                    | 说明                                                                                                                                                           |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `card_limit`          | 卡片消费上限。Business Mastercard 和 Personal Visa 必填（必须 ≥ 0.01）；Business Visa 可选（省略时默认为 0；传入时必须 ≥ 0）。参见 [卡产品](/zh/card-issuance/v1.6/guide/card-products) 确认你的产品类型。 |
| `spending_controls`   | 单笔消费限额 —— 参见 [消费限额](/zh/card-issuance/v1.6/guide/spending-controls)                                                                                          |
| `risk_controls`       | 配置 3DS 行为（`enable_3ds`、`allow_3ds_transactions`）—— 参见 [3D Secure](/zh/card-issuance/v1.6/guide/3d-secure)                                                    |
| `metadata`            | 键值对形式的自定义元信息（最多 3200 字节）                                                                                                                                     |
| `card_art_id`         | 应用于新卡的卡面 —— 参见 [卡面](/zh/card-issuance/v1.6/guide/card-art)。省略时使用账户默认卡面。                                                                                      |
| `usage_type`          | `NORMAL`（默认）或 `ONE_TIME`（一次性卡）                                                                                                                               |
| `auto_cancel_trigger` | 仅 `ONE_TIME` 卡支持：`ON_AUTH` 或 `ON_CAPTURE`                                                                                                                    |

<h2 id="step-3-receive-the-webhook">步骤3：接收 webhook</h2>

处理完成后，UQPAY 会发送 `card.create.succeeded` 或 `card.create.failed` webhook。在 [webhook 配置](/zh/account-center/v1.6/guide/webhooks-setting) 中订阅这些事件。

**示例：`card.create.succeeded`**

```json theme={null}
{
  "version": "V1.6.0",
  "event_name": "ISSUING",
  "event_type": "card.create.succeeded",
  "event_id": "8d62450e-11cd-4e62-b774-bbb52ac959df",
  "source_id": "79224316-ecad-4e61-9eeb-e7929bda124c",
  "data": {
    "card_available_balance": "1000",
    "card_bin": "40963608",
    "card_id": "50418faa-57a8-4ce2-9157-621b00b13a3b",
    "card_number": "40963608****1764",
    "card_product_id": "467e993f-317a-49fc-9ea0-bf49de7d1f76",
    "card_scheme": "VISA",
    "card_status": "ACTIVE",
    "cardholder": {
      "cardholder_id": "25ea804d-7fd5-43d5-8792-0fc0214cdb2f",
      "cardholder_status": "SUCCESS",
      "create_time": "2026-04-10T18:03:47+08:00",
      "email": "quickstart-1775815424@example.com",
      "first_name": "Alex",
      "last_name": "Chen"
    },
    "form_factor": "VIRTUAL",
    "metadata": {},
    "mode_type": "SHARE",
    "risk_control": {
      "enable_3ds": "Y",
      "allow_3ds_transactions": "Y"
    },
    "spending_limits": [
      {
        "amount": "20000",
        "interval": "PER_TRANSACTION"
      }
    ]
  }
}
```

<h2 id="step-4-retrieve-sensitive-card-details">步骤4：查询卡片敏感信息</h2>

向持卡人展示完整卡号、过期日期和 CVV 时，使用 [安全卡片展示（iframe）](/zh/card-issuance/v1.6/guide/secure-iframe-guide) 集成方案，避免在你的后端暴露敏感卡数据。

如果你的系统已通过 PCI DSS 合规认证，也可以使用 [Retrieve Sensitive Card Details](/zh/card-issuance/v1.6/api-reference/retrieve-card-secure) 接口。

<h2 id="related">相关阅读</h2>

* [核心概念](/zh/card-issuance/v1.6/guide/core-concepts) —— 卡形态、卡模式与卡设置
* [签发实体卡](/zh/card-issuance/v1.6/guide/issue-physical-cards) —— 绑定并激活实体卡
* [卡生命周期](/zh/card-issuance/v1.6/guide/card-lifecycle) —— 冻结、解除冻结或注销卡片
* [Card Created webhook](/zh/card-issuance/v1.6/webhooks/card-created)
* [Create Card API](/zh/card-issuance/v1.6/api-reference/create-card)