> ## 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.
# Issue virtual cards
> Create virtual cards through the API and deliver card credentials to cardholders.
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**
* A cardholder with `cardholder_status: SUCCESS` — see [Create cardholders](/card-issuance/v1.6/guide/create-and-manage-cardholders)
* Sufficient issuing balance if using a Single mode product — see [Fund your issuing balance](/card-issuance/v1.6/guide/fund-your-issuing-balance)
## Step 1: Select a card product
List the card products available on your account to find one with `card_form` containing `VIR`.
```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"
```
```json theme={null}
{
"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](/card-issuance/v1.6/api-reference/simulate-authorization), choose a product with BIN `40963608`.
## Step 2: Create the card
Call the [Create Card](/card-issuance/v1.6/api-reference/create-card) endpoint with the cardholder ID, product ID, currency, and card limit.
```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
}'
```
**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 seconds, it transitions to `ACTIVE`.
### Optional parameters
| Parameter | Description |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `card_limit` | Spending cap for the card. Required for Business Mastercard and Personal Visa (must be ≥ 0.01); optional for Business Visa (defaults to 0 if omitted; must be ≥ 0 if provided). See [Card products](/card-issuance/v1.6/guide/card-products) to identify your product. |
| `spending_controls` | Per-transaction spending limits — see [Spending controls](/card-issuance/v1.6/guide/spending-controls) |
| `risk_controls` | Configure 3DS behavior (`enable_3ds`, `allow_3ds_transactions`) — see [3D Secure](/card-issuance/v1.6/guide/3d-secure) |
| `metadata` | Key-value pairs for your own reference (max 3200 bytes) |
| `card_art_id` | Card art to apply to the new card — see [Card art](/card-issuance/v1.6/guide/card-art). Omit to use the account's default. |
| `usage_type` | `NORMAL` (default) or `ONE_TIME` for single-use cards |
| `auto_cancel_trigger` | For `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](/account-center/v1.6/guide/webhooks-setting).
**Example: `card.create.succeeded`**
```json theme={null}
{
"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": {
"enable_3ds": "Y",
"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)](/card-issuance/v1.6/guide/secure-iframe-guide) integration. This avoids exposing sensitive card data in your backend.
Alternatively, use the [Retrieve Sensitive Card Details](/card-issuance/v1.6/api-reference/retrieve-card-secure) endpoint if your system is PCI DSS compliant.
## Related
* [Core concepts](/card-issuance/v1.6/guide/core-concepts) — Card forms, modes, and settings
* [Issue physical cards](/card-issuance/v1.6/guide/issue-physical-cards) — Assign and activate physical cards
* [Card lifecycle](/card-issuance/v1.6/guide/card-lifecycle) — Freeze, unfreeze, or cancel cards
* [Card Created webhook](/card-issuance/v1.6/webhooks/card-created)
* [Create Card API](/card-issuance/v1.6/api-reference/create-card)