Update a virtual card

PATCH

/virtual-cards/{id}

Updates mutable fields on an existing virtual card belonging to the authenticated entity: description, client_meta, and status. Only fields included in the request body are changed — omitted fields retain their current values. Structural fields (currency, account_id, cardholder, billing_address, masked_pan, expiry, type, card_brand) cannot be changed after creation. Setting status to frozen suspends the card for new authorizations; setting it back to active re-enables it. A card that is still pending-approval (awaiting maker-checker sign-off on its creation) cannot have its status changed via this endpoint until that approval completes.

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

Body Params application/jsonRequired

Examples

Responses

🟢200

application/json

Virtual card updated successfully. Returns the full card object reflecting the applied changes.

Bodyapplication/json

🟠400

🟠401

🟠404

Request Example

Shell

JavaScript

Java

Swift

cURL

Update only the descriptionFreeze the cardUpdate spending limitsUpdate all mutable fields

curl --location --request PATCH '/virtual-cards/01HQZR2BKPFQ8MXJVT3G7LWNE' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{
    "description": "Marketing team subscriptions card"
}'

Response Example

200 - Success

{
    "message": "Virtual card updated successfully",
    "status": "success",
    "data": {
        "id": "01HQZR2BKPFQ8MXJVT3G7LWNE",
        "entity_id": "01HQZR2BKPFQ8MXJVT3G7LWNA",
        "account_id": "01HQZR2BKPFQ8MXJVT3G7LWNB",
        "cardholder": {
            "name": "Ada Lovelace",
            "email": "ada.lovelace@example.com"
        },
        "billing_address": {
            "line_one": "221B Baker Street",
            "country": "GB",
            "code": "NW16XE",
            "code_type": "postal",
            "city": "London",
            "state": "London"
        },
        "masked_pan": "424242****4242",
        "expiry": {
            "month": "09",
            "year": "30"
        },
        "currency": "USD",
        "status": "frozen",
        "description": "Marketing team subscriptions card",
        "cached_balance": 25000,
        "creation_fee": 500,
        "type": "self-contained",
        "card_brand": "visa",
        "client_reference": "vc-ref-20260806-001",
        "client_meta": {
            "department": "marketing",
            "cost_center": "CC-014"
        },
        "limits": {
            "per_transaction": 10000,
            "daily": 50000,
            "monthly": 200000
        },
        "maker_checker_approver_group_id": null,
        "created": 1754524800000,
        "updated": 1754611200000
    }
}

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

List virtual cards

Retrieve a virtual card