Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developers-sandbox.uqpaytech.com/llms.txt

Use this file to discover all available pages before exploring further.

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
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 protected] \
  -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.
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.
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.
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": "[email protected]",
        "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.