Retrieve a virtual card

GET

/virtual-cards/{id}

Fetches a single virtual card by its unique identifier. The card must belong to the authenticated entity — the entity_id from the bearer token is automatically applied as a scoping condition, so callers cannot retrieve virtual cards belonging to other entities. Returns the card's masked PAN, expiry, cardholder details, cached balance, and current lifecycle status. The full, unmasked card number is never returned by this endpoint.

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 ********************

Path Params

Responses

🟢200

application/json

Virtual card found and returned successfully.

Bodyapplication/json

🟠400

🟠401

🟠404

Request Example

Shell

JavaScript

Java

Swift

curl --location '/virtual-cards/01J8Z6R2BKPFQ8MXJVT3G7LWNE' \
--header 'Authorization: Bearer <token>'

Response Example

200 - Success

{
    "message": "Virtual card retrieved successfully",
    "status": "success",
    "data": {
        "id": "01J8Z6R2BKPFQ8MXJVT3G7LWNE",
        "entity_id": "01HQZR2BKPFQ8MXJVT3G7LWNA",
        "account_id": "01HQZR2BKPFQ8MXJVT3G7LWN1",
        "cardholder": {
            "name": "Ada Lovelace",
            "email": "ada@example.com"
        },
        "billing_address": {
            "line_one": "221B Baker Street",
            "country": "GB",
            "code": "NW16XE",
            "code_type": "postal",
            "city": "London",
            "state": "London"
        },
        "masked_pan": "412345****6789",
        "expiry": {
            "month": "09",
            "year": "30"
        },
        "currency": "USD",
        "status": "active",
        "description": "Marketing team subscriptions card",
        "cached_balance": 50000,
        "creation_fee": 250,
        "type": "self-contained",
        "card_brand": "visa",
        "client_reference": "card-ref-20260806-001",
        "client_meta": {
            "department": "marketing",
            "cost_center": "CC-014"
        },
        "maker_checker_approver_group_id": null,
        "payment_intent_id": "01HZAB1234567890ABCDEFGH02",
        "payout_intent_id": "01HZAB1234567890ABCDEFGH03",
        "limits": {
            "per_transaction": 20000,
            "daily": 100000,
            "monthly": 500000
        },
        "created": 1754524800000,
        "updated": 1754524800000
    }
}

Modified at 2026-09-30 00:29:30

Update a virtual card

Record a decision on a maker-checker action