Skip to main content
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

​
Step 1: Create a cardholder

A cardholder represents the person who will use the card. Create one with a name, email, phone number, and country code. 
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
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.

​
Step 2: Find a card product

Card products define the BIN, card scheme, funding mode, and supported currencies. List the products available on your account. 
uqpay issuing product list
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.

​
Step 3: Create a virtual card

Issue a virtual card to the cardholder using the product you selected. 
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
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.

​
Step 4: Verify the card

Retrieve the card to confirm it is active. 
uqpay issuing card list \
  --cardholder-id 25ea804d-7fd5-43d5-8792-0fc0214cdb2f
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.

​
Next steps