Quickstart

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.

Prerequisites

A UQPAY sandbox account with Card Issuance enabled
An API token from the Access Token endpoint
The UQPAY CLI installed (recommended), or curl

Create a cardholder

A cardholder represents the person who will use the card. Create one with a name, email, phone number, and country code.

CLI
curl

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

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

Response:

{
  "cardholder_id": "25ea804d-7fd5-43d5-8792-0fc0214cdb2f",
  "cardholder_status": "SUCCESS"
}

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

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.

Find a card product

Card products define the BIN, card scheme, funding mode, and supported currencies. List the products available on your account.

CLI
curl

uqpay issuing product list

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"

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 endpoint.Example product (abbreviated):

{
  "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.

Create a virtual card

Issue a virtual card to the cardholder using the product you selected.

CLI
curl

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

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

Response:

{
  "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 fires. Virtual cards do not require activation.

Verify the card

Retrieve the card to confirm it is active.

CLI
curl

uqpay issuing card list \
  --cardholder-id 25ea804d-7fd5-43d5-8792-0fc0214cdb2f

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"

Response:

{
  "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.

What’s next

Simulate a transaction

Use the Simulator API to test authorization and reversal flows.

Core concepts

Learn about card forms, funding modes, and configuration options.

Spending controls

Set per-transaction limits and merchant category restrictions.

Card lifecycle

Freeze, unfreeze, or cancel a card.

Getting Started

Cardholders

Cards

Funding

Controls & Security

Integration

Reference

What’s next

Simulate a transaction

Core concepts

Spending controls

Card lifecycle

​What’s next

Simulate a transaction

Core concepts

Spending controls

Card lifecycle

What’s next