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

# Quickstart

> Issue your first virtual card in a few API calls.

This guide walks you through issuing a virtual card on the sandbox environment. By the end, you will have a cardholder with an active virtual card ready to simulate transactions.

<Info>
  **Prerequisites**

  * A UQPAY sandbox account with Card Issuance enabled
  * An API token from the [Access Token](/account-center/v1.6/api-reference/access-token) endpoint
  * The [UQPAY CLI](/developer-tools/cli/overview) installed (recommended), or `curl`
</Info>

<Steps>
  <Step title="Create a cardholder">
    A cardholder represents the person who will use the card. Create one with a name, email, phone number, and country code.

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

    **Response:**

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

    Save the `cardholder_id` — you need it to create a card.

    <Note>
      Some card products require Enhanced KYC. If `cardholder_status` returns `PENDING`, the cardholder must complete identity verification before you can issue a card. See [KYC verification](/card-issuance/v1.6/guide/enhanced-kyc-card-issuance).
    </Note>
  </Step>

  <Step title="Find a card product">
    Card products define the BIN, card scheme, funding mode, and supported currencies. List the products available on your account.

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

    Look for a product with `card_form` containing `VIR` (virtual). For sandbox simulation, use a product with BIN `40963608` — this is the only BIN that supports the [Simulate Authorization](/card-issuance/v1.6/api-reference/simulate-authorization) endpoint.

    **Example product (abbreviated):**

    ```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"
    }
    ```

    Save the `product_id` to use in the next step.
  </Step>

  <Step title="Create a virtual card">
    Issue a virtual card to the cardholder using the product you selected.

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

    **Response:**

    ```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"
    }
    ```

    The card starts in `PENDING` status. Within a few seconds, it transitions to `ACTIVE` and a `card.create.succeeded` [webhook](/card-issuance/v1.6/webhooks/card-created) fires. Virtual cards do not require activation.
  </Step>

  <Step title="Verify the card">
    Retrieve the card to confirm it is active.

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

    **Response:**

    ```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"
        }
      ]
    }
    ```

    The card is `ACTIVE` with an available balance of `1000.00 USD`. It is ready to simulate transactions.
  </Step>
</Steps>

## What's next

<CardGroup cols={2}>
  <Card title="Simulate a transaction" href="/card-issuance/v1.6/guide/testing-in-sandbox" icon="fa-flask-vial">
    Use the Simulator API to test authorization and reversal flows.
  </Card>

  <Card title="Core concepts" href="/card-issuance/v1.6/guide/core-concepts" icon="fa-book">
    Learn about card forms, funding modes, and configuration options.
  </Card>

  <Card title="Spending controls" href="/card-issuance/v1.6/guide/spending-controls" icon="fa-sliders">
    Set per-transaction limits and merchant category restrictions.
  </Card>

  <Card title="Card lifecycle" href="/card-issuance/v1.6/guide/card-lifecycle" icon="fa-rotate">
    Freeze, unfreeze, or cancel a card.
  </Card>
</CardGroup>