Create a virtual card

Issues a new self-contained virtual card funded from one of your accounts. The card is created active immediately, or pending-approval when the entity has a default maker-checker approver group configured for card creation — in that case, no funds are moved and no card is issued by the provider until the request is fully approved.

When the card is created active, the requested initial_balance (plus any applicable creation fee) is debited from account_id via the ledger in the same transaction as card creation, and a card number, expiry, and billing address are issued by the card-issuing provider. If the transfer fails due to insufficient available balance, the entire operation is rolled back and no card is created.

The client_reference you supply must be unique per entity; attempting to create a second card with the same reference for the same entity fails with a 400 error rather than creating a duplicate.

When called with a JWT session, this endpoint also requires a valid, unused money_action_confirmation_id (minted via POST /money-action-confirmations with action_type card_issuance after the caller re-confirms their PIN) in the request body. This requirement is skipped entirely for secret-API-key requests, since PIN confirmation only applies to interactive human sessions.

Request

Authorization

JWT Bearer

Add the parameter

Authorization

to Headers

Example:

Authorization: ********************

Bearer Token

Provide your bearer token in the

Authorization

header when making requests to protected resources.

Example:

Authorization: Bearer ********************

Body Params application/jsonRequired

Examples

application/json

The virtual card was created successfully, either as active (funded and issued) or pending-approval (awaiting maker-checker sign-off before any funds move or a card is issued).

Bodyapplication/json

curl --location '/virtual-cards' \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data-raw '{ "account_id": "01HXYZ1234567890ABCDEFGHIJ", "currency": "USD", "initial_balance": 0, "cardholder": { "name": "Ada Lovelace", "email": "ada.lovelace@example.com" }, "client_reference": "card_req_88abc123" }'

{ "message": "Virtual card created successfully", "status": "success", "data": { "id": "01HXYZ9876543210ZYXWVUTSRQ", "entity_id": "01HABC9999888877776666ZZZZ", "account_id": "01HXYZ1234567890ABCDEFGHIJ", "cardholder": { "name": "Ada Lovelace", "email": "ada.lovelace@example.com" }, "billing_address": { "line_one": "1600 Amphitheatre Parkway", "country": "US", "code": "94043", "code_type": "zip", "city": "Mountain View", "state": "CA" }, "masked_pan": "435621****4489", "expiry": { "month": "09", "year": "30" }, "currency": "USD", "status": "active", "description": "marketing-spend", "cached_balance": 100000, "creation_fee": 250, "type": "self-contained", "card_brand": "visa", "client_reference": "card_req_88abc123", "client_meta": { "department": "marketing", "internal_ref": "card-req-77" }, "maker_checker_approver_group_id": null, "payment_intent_id": "01HPAY1234567890ABCDEFGHIJ", "payout_intent_id": "01HPYO1234567890ABCDEFGHIJ", "limits": { "per_transaction": 50000, "daily": 200000, "monthly": 1000000 }, "created": 1754393520000, "updated": 1754393520000 } }

Request

Responses