> ## 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 调用，签发你的第一张虚拟卡。

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

<Info>
  **前置条件**

  * 已启用 Card Issuance 的 UQPAY 沙盒账户
  * 通过 [Access Token](/zh/account-center/v1.6/api-reference/access-token) 接口获取的 API Token
  * 已安装 [UQPAY CLI](/developer-tools/cli/overview)（推荐），或 `curl`
</Info>

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

    <Tabs>
      <Tab title="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>

      <Tab title="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"
          }'
        ```
      </Tab>
    </Tabs>

    **响应：**

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

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

    <Note>
      某些卡产品需要 Enhanced KYC。如果 `cardholder_status` 返回 `PENDING`，持卡人需要先完成身份验证才能签发卡片。参见 [KYC 验证](/zh/card-issuance/v1.6/guide/enhanced-kyc-card-issuance)。
    </Note>
  </Step>

  <Step title="查找卡产品">
    卡产品定义了 BIN、卡组织、资金模式和支持的币种。列出你账户下可用的卡产品。

    <Tabs>
      <Tab title="CLI">
        ```bash theme={null}
        uqpay issuing product list
        ```
      </Tab>

      <Tab title="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"
        ```
      </Tab>
    </Tabs>

    找一个 `card_form` 包含 `VIR`（虚拟）的卡产品。沙盒模拟场景下，使用 BIN 为 `40963608` 的卡产品 —— 这是唯一支持 [Simulate Authorization](/zh/card-issuance/v1.6/api-reference/simulate-authorization) 接口的 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`，下一步会用到。
  </Step>

  <Step title="创建一张虚拟卡">
    使用你选中的卡产品，为持卡人签发一张虚拟卡。

    <Tabs>
      <Tab title="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>

      <Tab title="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
          }'
        ```
      </Tab>
    </Tabs>

    **响应：**

    ```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](/zh/card-issuance/v1.6/webhooks/card-created)。虚拟卡不需要激活。
  </Step>

  <Step title="验证卡片">
    查询卡片，确认它已激活。

    <Tabs>
      <Tab title="CLI">
        ```bash theme={null}
        uqpay issuing card list \
          --cardholder-id 25ea804d-7fd5-43d5-8792-0fc0214cdb2f
        ```
      </Tab>

      <Tab title="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"
        ```
      </Tab>
    </Tabs>

    **响应：**

    ```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`。可以用于模拟交易。
  </Step>
</Steps>

<h2 id="what-s-next">下一步</h2>

<CardGroup cols={2}>
  <Card title="模拟交易" href="/zh/card-issuance/v1.6/guide/testing-in-sandbox" icon="fa-flask-vial">
    使用 Simulator API 测试授权和冲正流程。
  </Card>

  <Card title="核心概念" href="/zh/card-issuance/v1.6/guide/core-concepts" icon="fa-book">
    了解卡形态、资金模式和配置选项。
  </Card>

  <Card title="消费限额" href="/zh/card-issuance/v1.6/guide/spending-controls" icon="fa-sliders">
    设置单笔限额和商户类别限制。
  </Card>

  <Card title="卡生命周期" href="/zh/card-issuance/v1.6/guide/card-lifecycle" icon="fa-rotate">
    冻结、解除冻结或注销卡片。
  </Card>
</CardGroup>