Skip to main content
Virtual cards are created instantly and can be used for digital transactions immediately — no activation required. Each virtual card includes a PAN, expiration date, and CVV.
Prerequisites

​
Step 1: Select a card product

List the card products available on your account to find one with card_form containing VIR. 
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"

{
  "total_items": 2,
  "total_pages": 1,
  "data": [
    {
      "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 for the product you want to use.
To test with the Simulator, choose a product with BIN 40963608.

​
Step 2: Create the card

Call the Create Card endpoint with the cardholder ID, product ID, currency, and card limit. 
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 seconds, it transitions to ACTIVE.

​
Optional parameters

ParameterDescription
card_limitSpending cap for the card. Required for BINs 527735, 555071, 555243 (must be ≥ 0.01). Optional for all other BINs (defaults to 0 if omitted; must be ≥ 0 if provided).
spending_controlsPer-transaction spending limits — see Spending controls
risk_controlsEnable/disable 3DS (allow_3ds_transactions) — see 3D Secure
metadataKey-value pairs for your own reference (max 3200 bytes)
usage_typeNORMAL (default) or ONE_TIME for single-use cards
auto_cancel_triggerFor ONE_TIME cards: ON_AUTH or ON_CAPTURE

​
Step 3: Receive the webhook

UQPAY sends a card.create.succeeded or card.create.failed webhook after processing. Subscribe to these events in your webhook settings. Example: card.create.succeeded 
{
  "version": "V1.6.0",
  "event_name": "ISSUING",
  "event_type": "card.create.succeeded",
  "event_id": "8d62450e-11cd-4e62-b774-bbb52ac959df",
  "source_id": "79224316-ecad-4e61-9eeb-e7929bda124c",
  "data": {
    "card_available_balance": "1000",
    "card_bin": "40963608",
    "card_id": "50418faa-57a8-4ce2-9157-621b00b13a3b",
    "card_number": "40963608****1764",
    "card_product_id": "467e993f-317a-49fc-9ea0-bf49de7d1f76",
    "card_scheme": "VISA",
    "card_status": "ACTIVE",
    "cardholder": {
      "cardholder_id": "25ea804d-7fd5-43d5-8792-0fc0214cdb2f",
      "cardholder_status": "SUCCESS",
      "create_time": "2026-04-10T18:03:47+08:00",
      "email": "quickstart-1775815424@example.com",
      "first_name": "Alex",
      "last_name": "Chen"
    },
    "form_factor": "VIRTUAL",
    "metadata": {},
    "mode_type": "SHARE",
    "risk_control": {
      "allow_3ds_transactions": "Y"
    },
    "spending_limits": [
      {
        "amount": "20000",
        "interval": "PER_TRANSACTION"
      }
    ]
  }
}

​
Step 4: Retrieve sensitive card details

To display the full card number, expiration date, and CVV to the cardholder, use the Secure Card Display (iframe) integration. This avoids exposing sensitive card data in your backend. Alternatively, use the Retrieve Sensitive Card Details endpoint if your system is PCI DSS compliant.