Nuvion lets you issue two types of virtual cards on behalf of your entities: disposable single-use cards for one-off payments, and reusable virtual cards with configurable spending controls at the transaction, daily, and billing-cycle level. Both card types are funded from an existing entity account and can be reassigned, frozen, unfrozen, or soft-deleted at any time.
Card types Type Description Use case disposableSingle-use virtual card. Automatically blocked after the first successful transaction. Ad-hoc vendor payments, one-time subscriptions virtualReusable card with optional spending controls (limits by amount, transaction count, MCC). Employee expense cards, recurring vendor payments physicalPhysical card issued and mailed to the cardholder. Managed via the same card endpoints. Consumer wallets, debit card programs
Card statuses Status Description activeCard is in good standing and can be used for transactions. blockedCard is frozen or has been soft-deleted. No new transactions are authorized. fraudCard has been flagged for suspected fraud. Contact support to resolve.
Create a disposable card Issues a single-use virtual card funded from the specified account. The card is automatically blocked after its first successful transaction.
curl -X POST https://api.nuvion.dev/disposable-cards \ -H "Authorization: Bearer $NUVION_API_KEY " \ -H "Content-Type: application/json" \ -d '{ "account_id": "acc_01HXYZ5678EFGHIJKLMNOP", "card_name": "Alex Travel Card", "cardholder": { "email": "alex.johnson@example.com", "first_name": "Alex", "last_name": "Johnson", "phone_number": "+12125550198" }, "currency": "USD", "amount": 10000, "expiration_month": "12", "expiration_year": "27" }'
The ID of the account to fund the card from. Must be 26 characters.
A display name for the card. Used to identify the card in listings and the dashboard.
Details of the cardholder to associate with this card. The cardholder’s email address.
The cardholder’s first name.
The cardholder’s last name.
The cardholder’s phone number in E.164 format (e.g. +12125550198).
The ISO 4217 currency code for the card. Must be 3 characters (e.g. USD).
The amount to load onto the card in the smallest currency unit. 10000 = $100.00 USD.
The card expiration month in MM format (e.g. "12").
The card expiration year in YY format (e.g. "27").
Arbitrary key-value pairs you can attach to the card for your own reference. Not used by Nuvion.
{ "message" : "Virtual card created successfully" , "status" : "success" , "data" : { "status" : "active" , "id" : "crd_01HXYZ9012ABCD" , "name" : "Alex Travel Card" , "number" : "4111111111111234" , "expiration_month" : "12" , "expiration_year" : "27" , "cvv" : "123" , "individual_controls" : {}, "individual_mcc_controls" : [], "mcc_group_controls" : [] } }
Card status. One of active, blocked, or fraud.
Unique identifier for the card.
The display name assigned to the card.
The full card number (PAN). Treat as sensitive — never log or store.
Card expiration month (MM).
Card expiration year (YY).
Card verification value. Treat as sensitive — never log or store.
Spending controls applied to this card. Empty object for disposable cards.
MCC-specific spending controls. Empty array for disposable cards.
MCC group spending controls. Empty array for disposable cards.
Error codes: 400 Bad Request, 401 Unauthorized, 404 Not Found, 429 Too Many Requests (includes retry_after, limit_type, current_count, limit), 500 Internal Server Error.Create a virtual card Issues a reusable virtual card with optional spending controls. Controls can restrict by transaction amount, daily limits, billing cycle totals, and specific merchant category codes (MCCs).
curl -X POST https://api.nuvion.dev/virtual-cards \ -H "Authorization: Bearer $NUVION_API_KEY " \ -H "Content-Type: application/json" \ -d '{ "account_id": "acc_01HXYZ5678EFGHIJKLMNOP", "card_name": "Alex Travel Card", "currency": "USD", "amount": 10000, "cardholder": { "email": "alex.johnson@example.com", "first_name": "Alex", "last_name": "Johnson", "phone_number": "+12125550198" }, "individual_controls": { "billing_cycle": "Weekly", "billing_cycle_day": "Sunday", "daily_amount_limit": 50000, "daily_transaction_count": 10, "transaction_amount_limit": 20000 } }'
The ID of the account to fund the card from. Must be 26 characters.
A display name for the card.
The ISO 4217 currency code for the card (e.g. USD). Must be 3 characters.
The amount to load onto the card in the smallest currency unit. 10000 = $100.00 USD.
Details of the cardholder to associate with this card. The cardholder’s email address.
The cardholder’s first name.
The cardholder’s last name.
The cardholder’s phone number in E.164 format.
When true, enables transaction alerts for this card. Defaults to false.
Arbitrary key-value pairs for your own reference.
General spending controls applied to this card. All fields are optional. Show individual_controls fields
The billing cycle period. e.g. "Weekly", "Monthly".
The day the billing cycle resets. e.g. "Sunday" for a weekly cycle.
Maximum number of transactions allowed per billing cycle.
Maximum total spend per day in the smallest currency unit.
Maximum number of transactions allowed per day.
Maximum amount per individual transaction in the smallest currency unit.
Per-MCC spending controls. Each entry targets a specific merchant category code. Show individual_mcc_controls fields
The 4-digit Merchant Category Code to apply controls to.
When false, transactions at this MCC are blocked entirely. Defaults to true.
Maximum cumulative spend for this MCC in the smallest currency unit.
Maximum transactions at this MCC per billing cycle.
Maximum daily spend at this MCC in the smallest currency unit.
Maximum daily transactions at this MCC.
Maximum amount per individual transaction at this MCC.
Spending controls applied to a named group of MCCs. Show mcc_group_controls fields
The name of the MCC group (as configured in your Nuvion dashboard).
When false, all MCCs in this group are blocked. Defaults to true.
Maximum cumulative spend for this MCC group.
Maximum transactions for this MCC group per billing cycle.
Maximum daily spend for this MCC group.
Maximum daily transactions for this MCC group.
Maximum amount per individual transaction within this MCC group.
{ "message" : "Ghost card created successfully" , "status" : "success" , "data" : { "status" : "active" , "id" : "crd_01HXYZ9012ABCD" , "name" : "Alex Travel Card" , "number" : "4111111111111234" , "expiration_month" : "12" , "expiration_year" : "27" , "cvv" : "123" , "individual_controls" : { "billing_cycle" : "Weekly" , "billing_cycle_day" : "Sunday" , "cycle_transaction_count" : 0 , "daily_amount_limit" : 50000 , "daily_transaction_count" : 10 , "transaction_amount_limit" : 20000 }, "individual_mcc_controls" : [], "mcc_group_controls" : [], "created" : 1735725600000 } }
Card status. One of active, blocked, or fraud.
Unique identifier for the card.
The display name assigned to the card.
The full card number (PAN). Treat as sensitive.
Card expiration month (MM).
Card expiration year (YY).
Card verification value. Treat as sensitive.
The resolved spending controls on this card. Show individual_controls fields
The billing cycle period (e.g. "Weekly").
The day the billing cycle resets.
Max transactions per billing cycle.
Max transactions per day.
Max amount per individual transaction.
Resolved per-MCC controls. Each entry includes all limit fields plus mcc and open.
Resolved MCC group controls. Each entry includes group_name, open, and applicable limit fields.
Unix timestamp in milliseconds when the card was created.
Error codes: 400 Bad Request, 401 Unauthorized, 404 Not Found, 429 Too Many Requests, 500 Internal Server Error.List cards Returns a paginated list of cards for an entity. Soft-deleted cards are excluded. Frozen and blocked cards are included.
If account_id is omitted, this endpoint returns all cards across all accounts for the authenticated entity.
curl -G https://api.nuvion.dev/cards \ -H "Authorization: Bearer $NUVION_API_KEY " \ --data-urlencode "account_id=acc_01HXYZ5678EFGHIJKLMNOP" \ --data-urlencode "limit=20"
Filter cards by account. Must be 26 characters. If omitted, returns all cards for the entity.
Number of cards to return per page. Default 20, maximum 100.
Cursor for forward pagination. Use the next_cursor value from the previous response.
Cursor for backward pagination. Use the prev_cursor value from the previous response.
{ "data" : { "cards" : [ { "id" : "crd_01HXYZ9012ABCD" , "name" : "Alex Travel Card" , "status" : "active" , "created" : "2026-01-01T10:00:00.000Z" } ], "pagination" : { "has_next" : false , "has_previous" : false , "next_cursor" : null , "prev_cursor" : null } } }
Array of card summary objects. Unique identifier for the card.
Display name of the card.
Card status. One of active, blocked, or fraud.
ISO 8601 timestamp of when the card was created.
Pagination metadata. Whether a next page of results exists.
Whether a previous page of results exists.
Cursor to pass as cursor to retrieve the next page. null if no next page.
Cursor to pass as prev_cursor to retrieve the previous page. null if no previous page.
Error codes: 400 Bad Request, 401 Unauthorized, 403 Forbidden, 500 Internal Server Error (includes error_code, retry_recommended, support_reference).Get card details Returns full details for a single card, including sensitive card credentials, all spending controls, and real-time usage tracking (amount used, on hold, and remaining balance per limit dimension).
curl https://api.nuvion.dev/card-details/crd_01HXYZ9012ABCD \ -H "Authorization: Bearer $NUVION_API_KEY "
{ "data" : { "status" : "active" , "id" : "crd_01HXYZ9012ABCD" , "type" : "virtual" , "first_name" : "Alex" , "last_name" : "Johnson" , "number" : "4111111111111234" , "expiration_month" : "12" , "expiration_year" : "27" , "cvv" : "123" , "individual_controls" : { "billing_cycle" : "Weekly" , "billing_cycle_day" : "Sunday" , "cycle_transaction_count" : 20 , "daily_amount_limit" : 50000 , "daily_transaction_count" : 10 , "transaction_amount_limit" : 20000 , "amount_used" : 5000 , "amount_hold" : 0 , "amount_balance" : 5000 , "daily_transaction_count_used" : 1 , "daily_transaction_count_hold" : 0 , "daily_transaction_count_balance" : 9 , "daily_amount_limit_used" : 5000 , "daily_amount_limit_hold" : 0 , "daily_amount_limit_balance" : 45000 , "cycle_transaction_count_used" : 1 , "cycle_transaction_count_hold" : 0 , "cycle_transaction_count_balance" : 19 }, "individual_mcc_controls" : [], "mcc_group_controls" : [], "billing" : { "address_line_1" : "350 Fifth Avenue" , "address_line_2" : "Suite 4100" , "city" : "New York" , "state" : "NY" , "postal_code" : "10001" }, "shipping" : null } }
Card status. One of active, blocked, or fraud.
Unique identifier for the card.
Card type. One of disposable, virtual, or physical.
The full card number (PAN). Treat as sensitive.
Card expiration month (MM).
Card expiration year (YY).
Card verification value. Treat as sensitive.
Spending controls and real-time usage tracking for this card. Show individual_controls fields
The billing cycle period (e.g. "Weekly").
The day the billing cycle resets.
Max transactions per billing cycle.
Max transactions per day.
Max amount per individual transaction.
Total amount spent against the card balance this cycle.
Amount currently on hold (pending authorization).
Remaining spendable balance (loaded amount minus used and held).
daily_transaction_count_used
Number of transactions completed today.
daily_transaction_count_hold
Number of transactions currently pending today.
daily_transaction_count_balance
Remaining transactions allowed today.
Total amount spent today.
daily_amount_limit_balance
Remaining daily spend allowance.
cycle_transaction_count_used
Transactions completed this billing cycle.
cycle_transaction_count_hold
Transactions currently pending this billing cycle.
cycle_transaction_count_balance
Remaining transactions allowed this billing cycle.
data.individual_mcc_controls
Per-MCC controls with usage tracking. Each entry includes all limit fields, _used, _hold, and _balance tracking fields, plus mcc and open.
MCC group controls. Each entry includes group_name, open, and applicable limit and usage fields.
The billing address on file for this card. Street address line 2 (optional).
The shipping address for physical cards. null for virtual and disposable cards. Street address line 2 (optional).
Error codes: 400 Bad Request, 401 Unauthorized, 403 Forbidden, 422 Unprocessable Entity, 500 Internal Server Error.Get card transactions Returns a paginated list of transactions made with a specific card.
curl https://api.nuvion.dev/card-transactions/crd_01HXYZ9012ABCD \ -H "Authorization: Bearer $NUVION_API_KEY "
{ "data" : { "payments" : [ { "_id" : "txn_01HXYZ3456WXYZ" , "amount" : 5000 , "currency" : "USD" , "unique_reference" : "TXN-2026-0001" , "account_id" : "acc_01HXYZ5678EFGHIJKLMNOP" , "entity_id" : "ent_01HXYZ1234ABCD" , "counterparty_id" : "cpt_01HXYZ7890EFGH" , "status" : "completed" , "status_reason" : null , "narration" : "Online purchase" , "type" : "debit" , "payment_type" : "card" , "applicable_fee" : 0 , "initiator" : { "type" : "card" , "id" : "usr_01HXYZ1111AAAA" , "name" : "Alex Johnson" , "card_id" : "crd_01HXYZ9012ABCD" }, "recipient" : { "name" : "Acme Corp" , "address" : { "city" : "San Francisco" , "state" : "CA" , "postal_code" : "94105" , "country" : "US" } }, "meta" : { "provider_code" : "00" }, "deleted" : false , "created" : 1735725600000 , "updated" : 1735725600000 , "version" : 1 } ], "pagination" : { "order" : "desc" , "has_next" : false , "limit" : 20 , "has_previous" : false , "next_cursor" : null , "previous_cursor" : null } } }
Array of card transaction objects. Unique transaction identifier.
Transaction amount in the smallest currency unit.
Unique idempotency reference for the transaction.
The account that was debited.
The entity that owns the account.
The merchant or counterparty ID.
Transaction status (e.g. pending, completed, failed).
Human-readable reason for the current status. null when not applicable.
Description of the transaction.
Direction of the transaction — debit or credit.
Payment rail used (e.g. card).
Fee charged for this transaction in the smallest currency unit.
Details about who or what initiated the transaction. Initiator type (e.g. card).
The user ID of the initiating cardholder.
Full name of the initiating cardholder.
Merchant or recipient details. Merchant or recipient name.
Merchant address. ISO 3166-1 alpha-2 country code.
Additional metadata from the payment provider. Response code returned by the card network or processor.
Whether this transaction record has been soft-deleted.
Unix timestamp in milliseconds when the transaction was created.
Unix timestamp in milliseconds when the transaction was last updated.
Optimistic concurrency version counter for the transaction record.
Pagination metadata. Sort order. One of desc or asc.
Whether a next page of results exists.
Number of results returned per page.
Whether a previous page of results exists.
Cursor for the next page. null if no next page.
Cursor for the previous page. null if no previous page.
Error codes: 400 Bad Request, 401 Unauthorized, 403 Forbidden, 422 Unprocessable Entity, 500 Internal Server Error.Manage a card Freeze a card Sets the card status to blocked. All authorization requests are declined while the card is frozen. The card record and spending history are preserved.
curl -X PATCH https://api.nuvion.dev/card-details/crd_01HXYZ9012ABCD/freeze \ -H "Authorization: Bearer $NUVION_API_KEY "
{ "data" : { "status" : "blocked" , "updated" : 1735725600000 } }
Error codes: 400 Bad Request, 401 Unauthorized, 500 Internal Server Error.Unfreeze a card Restores a frozen card to active status. Subsequent authorization requests are processed normally.
curl -X PATCH https://api.nuvion.dev/card-details/crd_01HXYZ9012ABCD/unfreeze \ -H "Authorization: Bearer $NUVION_API_KEY "
{ "data" : { "status" : "active" , "updated" : 1735725600000 } }
Error codes: 400 Bad Request, 401 Unauthorized, 500 Internal Server Error.Reassign card to a different account Moves the card to a different account. If the target account’s currency differs from the card’s transaction currency, Nuvion automatically applies FX conversion at the prevailing rate.
If the target account operates in a different currency, FX conversion is applied automatically. Review your platform’s FX rate agreement before reassigning cross-currency cards.
curl -X PATCH https://api.nuvion.dev/cards/crd_01HXYZ9012ABCD/account \ -H "Authorization: Bearer $NUVION_API_KEY " \ -H "Content-Type: application/json" \ -d '{ "account_id": "acc_01HXYZ5678EFGHIJKLMNOP" }'
The ID of the account to reassign the card to. Must be 26 characters. Returns 409 Conflict if the card is already assigned to this account.
{ "data" : { "card_id" : "crd_01HXYZ9012ABCD" , "account_id" : "acc_01HXYZ5678EFGHIJKLMNOP" } }
Error codes: 400 Bad Request, 401 Unauthorized, 404 Not Found, 409 Conflict (card already assigned to this account), 500 Internal Server Error.Delete a card Soft-deletes the card. The card is immediately blocked and removed from all card listings. The underlying record is retained for audit and transaction history purposes.
Deletion is not reversible. A deleted card cannot be reactivated. Issue a new card if the cardholder needs continued access.
curl -X DELETE https://api.nuvion.dev/card-details/crd_01HXYZ9012ABCD \ -H "Authorization: Bearer $NUVION_API_KEY "
{ "data" : { "status" : "blocked" , "deleted" : 1735725600000 } }
Error codes: 400 Bad Request, 401 Unauthorized, 500 Internal Server Error.What’s next
Accounts Understand how accounts are structured and how to fund a card from an entity account.
Accept a Payment Accept inbound payments into entity accounts before loading cards.
Errors Full reference for error codes, error object schema, and resolution guidance.
