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

# 快速开始

> 通过几次 API 调用，签发你的第一张虚拟卡。

本指南将引导你在沙盒环境中签发一张虚拟卡。完成之后，你将拥有一位持卡人和一张已激活的虚拟卡，可用于模拟交易。

> [!NOTE]
>
> **前置条件**
>
> * 已启用 Card Issuance 的 UQPAY 沙盒账户
> * 通过 [Access Token](https://developers-sandbox.uqpaytech.com/docs/zh/account-center/v1.6/api-reference/access-token.md) 接口获取的 API Token
> * 已安装 [UQPAY CLI](https://developers-sandbox.uqpaytech.com/docs/developer-tools/cli/overview.md)（推荐），或 `curl`

**1. 创建持卡人**

持卡人代表将使用这张卡的人。用姓名、邮箱、手机号和国家代码创建一个持卡人。

> [tab] CLI
>
> ```bash theme={null}
> uqpay issuing cardholder create \
>   -d first_name=Alex \
>   -d last_name=Chen \
>   -d email=alex.chen@example.com \
>   -d country_code=SG \
>   -d phone_number=91234567
> ```

> [tab] curl
>
> ```bash theme={null}
> curl -X POST https://api-sandbox.uqpaytech.com/api/v1/issuing/cardholders \
>   -H "x-auth-token: YOUR_API_TOKEN" \
>   -H "x-idempotency-key: $(uuidgen | tr '[:upper:]' '[:lower:]')" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "first_name": "Alex",
>     "last_name": "Chen",
>     "email": "alex.chen@example.com",
>     "country_code": "SG",
>     "phone_number": "91234567"
>   }'
> ```

**响应：**

```json theme={null}
{
  "cardholder_id": "25ea804d-7fd5-43d5-8792-0fc0214cdb2f",
  "cardholder_status": "SUCCESS"
}
```

保存 `cardholder_id` —— 创建卡片时需要用到它。

> [!NOTE]
>
> 某些卡产品需要 Enhanced KYC。如果 `cardholder_status` 返回 `PENDING`，持卡人需要先完成身份验证才能签发卡片。参见 [KYC 验证](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/guide/enhanced-kyc-card-issuance.md)。

**2. 查找卡产品**

卡产品定义了 BIN、卡组织、资金模式和支持的币种。列出你账户下可用的卡产品。

> [tab] CLI
>
> ```bash theme={null}
> uqpay issuing product list
> ```

> [tab] curl
>
> ```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"
> ```

找一个 `card_form` 包含 `VIR`（虚拟）的卡产品。沙盒模拟场景下，使用 BIN 为 `40963608` 的卡产品 —— 这是唯一支持 [Simulate Authorization](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/api-reference/simulate-authorization.md) 接口的 BIN。

**卡产品示例（节选）：**

```json theme={null}
{
  "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`，下一步会用到。

**3. 创建一张虚拟卡**

使用你选中的卡产品，为持卡人签发一张虚拟卡。

> [tab] CLI
>
> ```bash theme={null}
> uqpay issuing card create \
>   -d cardholder_id=25ea804d-7fd5-43d5-8792-0fc0214cdb2f \
>   -d card_product_id=467e993f-317a-49fc-9ea0-bf49de7d1f76 \
>   -d card_currency=USD \
>   -d card_limit=1000
> ```

> [tab] curl
>
> ```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`，同时触发 `card.create.succeeded` [webhook](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/webhooks/card-created.md)。虚拟卡不需要激活。

**4. 验证卡片**

查询卡片，确认它已激活。

> [tab] CLI
>
> ```bash theme={null}
> uqpay issuing card list \
>   --cardholder-id 25ea804d-7fd5-43d5-8792-0fc0214cdb2f
> ```

> [tab] curl
>
> ```bash theme={null}
> curl "https://api-sandbox.uqpaytech.com/api/v1/issuing/cards?cardholder_id=25ea804d-7fd5-43d5-8792-0fc0214cdb2f&page_number=1&page_size=10" \
>   -H "x-auth-token: YOUR_API_TOKEN" \
>   -H "Content-Type: application/json"
> ```

**响应：**

```json theme={null}
{
  "total_items": 1,
  "total_pages": 1,
  "data": [
    {
      "card_id": "50418faa-57a8-4ce2-9157-621b00b13a3b",
      "card_bin": "40963608",
      "card_number": "40963608****1764",
      "card_scheme": "VISA",
      "card_status": "ACTIVE",
      "card_currency": "USD",
      "card_limit": "1000.00",
      "available_balance": "1000.00",
      "consumed_amount": "0.00",
      "form_factor": "VIRTUAL",
      "mode_type": "SHARE",
      "cardholder": {
        "cardholder_id": "25ea804d-7fd5-43d5-8792-0fc0214cdb2f",
        "first_name": "Alex",
        "last_name": "Chen",
        "email": "quickstart-1775815424@example.com",
        "cardholder_status": "SUCCESS",
        "create_time": "2026-04-10T18:03:47+08:00"
      },
      "create_time": "2026-04-10T18:04:44+08:00"
    }
  ]
}
```

卡片状态为 `ACTIVE`，可用余额为 `1000.00 USD`。可以用于模拟交易。

## 下一步

> [card] [模拟交易](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/guide/testing-in-sandbox.md)
>
> 使用 Simulator API 测试授权和冲正流程。

> [card] [核心概念](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/guide/core-concepts.md)
>
> 了解卡形态、资金模式和配置选项。

> [card] [消费限额](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/guide/spending-controls.md)
>
> 设置单笔限额和商户类别限制。

> [card] [卡生命周期](https://developers-sandbox.uqpaytech.com/docs/zh/card-issuance/v1.6/guide/card-lifecycle.md)
>
> 冻结、解除冻结或注销卡片。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.