Cards are funded from an entity account and can be issued as single-use disposable cards or reusable virtual cards with configurable spending controls. All cards are managed through the same lifecycle endpoints — freeze, unfreeze, reassign, and delete.
The Card object Display name assigned to the card.
Card status. One of active, blocked, or fraud.
Card type. One of disposable, virtual, or physical.
Full card number (PAN). Treat as sensitive — never log or store.
Card expiration month in MM format.
Card expiration year in YY format.
Card verification value. Treat as sensitive — never log or store.
Spending controls and real-time usage tracking. Empty object for disposable cards. Show individual_controls fields
Billing cycle period. e.g. "Weekly", "Monthly".
Day the billing cycle resets. e.g. "Sunday".
Max transactions per billing cycle.
Max total spend per day in the smallest currency unit.
Max transactions per day.
Max amount per individual transaction in the smallest currency unit.
Total amount spent this billing cycle.
Amount currently on hold (pending authorization).
Remaining spendable balance.
daily_transaction_count_used
Transactions completed today.
daily_transaction_count_hold
Transactions 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 pending this billing cycle.
cycle_transaction_count_balance
Remaining transactions allowed this billing cycle.
Per-MCC spending controls. Each entry includes all limit and usage fields plus mcc and open. Empty array if no MCC controls are set.
MCC group spending controls. Each entry includes group_name, open, and applicable limit and usage fields. Empty array if no group controls are set.
Billing address on file for the card. Shipping address for physical cards. null for virtual and disposable cards. Same shape as billing.
Unix timestamp in milliseconds when the card was created.
Create a disposable card POST /disposable-cardsIssues a single-use virtual card funded from the specified account. The card is automatically blocked after its first successful transaction.
Request parameters The ID of the account to fund the card from.
Display name for the card. Used in listings and the dashboard.
Identity details for the cardholder. Phone number in E.164 format. e.g. +12125550198.
ISO 4217 currency code for the card. e.g. USD.
Amount to load onto the card in the smallest currency unit. 10000 = $100.00 USD.
Card expiration month in MM format. e.g. "12".
Card expiration year in YY format. e.g. "27".
Arbitrary key-value metadata.
Request curl -X POST https://api.nuvion.dev/disposable-cards \ -H "Authorization: Bearer $NUVION_API_KEY " \ -H "Content-Type: application/json" \ -d '{ "account_id": "01K747KD7QW8KQS2GRD8MQBT55", "card_name": "Vendor One-Time Payment", "cardholder": { "first_name": "Alex", "last_name": "Johnson", "email": "alex.johnson@example.com", "phone_number": "+12125550198" }, "currency": "USD", "amount": 10000, "expiration_month": "12", "expiration_year": "27" }'
Response Returns the created card object with status: "active". Card credentials (number, cvv) are included in the creation response only.
{ "status" : "success" , "data" : { "id" : "crd_01HXYZ9012ABCD" , "name" : "Vendor One-Time Payment" , "status" : "active" , "number" : "4111111111111234" , "expiration_month" : "12" , "expiration_year" : "27" , "cvv" : "123" , "individual_controls" : {}, "individual_mcc_controls" : [], "mcc_group_controls" : [] } }
Errors Code Description 400Validation error — a required field is missing or invalid. 404The account_id was not found. 429Rate limit exceeded. Response includes retry_after, limit_type, current_count, and limit.
Create a virtual card POST /virtual-cardsIssues a reusable virtual card with optional spending controls. Controls can restrict spend by transaction amount, daily totals, billing cycle totals, and specific merchant category codes (MCCs).
Request parameters The ID of the account to fund the card from.
Display name for the card.
ISO 4217 currency code for the card. e.g. USD.
Amount to load onto the card in the smallest currency unit.
Identity details for the cardholder. Same shape as disposable card cardholder.
General spending controls. All fields are optional. Show individual_controls fields
Billing cycle period. e.g. "Weekly", "Monthly".
Day the billing cycle resets. e.g. "Sunday" for a weekly cycle.
Max transactions per billing cycle.
Max total spend per day in the smallest currency unit.
Max transactions per day.
Max 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
4-digit Merchant Category Code.
When false, all transactions at this MCC are blocked. Defaults to true.
Max cumulative spend for this MCC in the smallest currency unit.
Max transactions at this MCC per billing cycle.
Max daily spend at this MCC.
Max daily transactions at this MCC.
Max amount per individual transaction at this MCC.
Spending controls applied to a named group of MCCs configured in your Nuvion dashboard. Show mcc_group_controls fields
When false, all MCCs in this group are blocked. Defaults to true.
Max cumulative spend for this group.
Max transactions for this group per billing cycle.
Max daily spend for this group.
Max daily transactions for this group.
Max amount per individual transaction within this group.
When true, enables transaction alerts for this card. Defaults to false.
Arbitrary key-value metadata.
Request curl -X POST https://api.nuvion.dev/virtual-cards \ -H "Authorization: Bearer $NUVION_API_KEY " \ -H "Content-Type: application/json" \ -d '{ "account_id": "01K747KD7QW8KQS2GRD8MQBT55", "card_name": "Marketing Team Card", "currency": "USD", "amount": 500000, "cardholder": { "first_name": "Alex", "last_name": "Johnson", "email": "alex.johnson@example.com", "phone_number": "+12125550198" }, "individual_controls": { "billing_cycle": "Weekly", "billing_cycle_day": "Sunday", "daily_amount_limit": 50000, "daily_transaction_count": 10, "transaction_amount_limit": 20000 } }'
Response Returns the created card object. Card credentials (number, cvv) are included in the creation response only.
{ "status" : "success" , "data" : { "id" : "crd_01HXYZ9012ABCD" , "name" : "Marketing Team Card" , "status" : "active" , "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" : 1760434049154 } }
Errors Code Description 400Validation error — a required field is missing or invalid. 404The account_id was not found. 429Rate limit exceeded.
List cards GET /cardsReturns a paginated list of cards. Soft-deleted cards are excluded; frozen and blocked cards are included.
Query parameters Filter by account. If omitted, returns all cards across all accounts for the entity.
Number of results per page. Between 1 and 100. Defaults to 20.
Pagination cursor for the next page. Use next_cursor from the previous response.
Pagination cursor for the previous page. Use prev_cursor from the previous response.
Request curl "https://api.nuvion.dev/cards?account_id=01K747KD7QW8KQS2GRD8MQBT55&limit=20" \ -H "Authorization: Bearer $NUVION_API_KEY "
Response { "data" : { "cards" : [ { "id" : "crd_01HXYZ9012ABCD" , "name" : "Marketing Team Card" , "status" : "active" , "created" : 1760434049154 } ], "pagination" : { "has_next" : false , "has_previous" : false , "next_cursor" : null , "prev_cursor" : null } } }
Get card details GET /card-details/{card_id}Returns full details for a single card, including sensitive credentials and real-time spending control usage.
This endpoint returns the card number and cvv. Ensure your server-side code never logs or stores these values.
Path parameters Request curl "https://api.nuvion.dev/card-details/crd_01HXYZ9012ABCD" \ -H "Authorization: Bearer $NUVION_API_KEY "
Response Returns the full Card object , including credentials and usage tracking.
{ "data" : { "id" : "crd_01HXYZ9012ABCD" , "name" : "Marketing Team Card" , "status" : "active" , "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" : 495000 , "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 } }
Errors Code Description 403The card does not belong to the authenticated entity. 404The card was not found.
Get card transactions GET /card-transactions/{card_id}Returns a paginated list of transactions made with a specific card.
Path parameters Query parameters Number of results per page. Defaults to 20.
Cursor for the next page.
Request curl "https://api.nuvion.dev/card-transactions/crd_01HXYZ9012ABCD" \ -H "Authorization: Bearer $NUVION_API_KEY "
Response { "data" : { "payments" : [ { "id" : "txn_01HXYZ3456WXYZ" , "amount" : 5000 , "currency" : "USD" , "unique_reference" : "TXN-2026-0001" , "account_id" : "01K747KD7QW8KQS2GRD8MQBT55" , "entity_id" : "01K3HJAK85YJP13WJ41P3CWAVM" , "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" }, "created" : 1760434049154 , "updated" : 1760434050159 } ], "pagination" : { "order" : "desc" , "has_next" : false , "has_previous" : false , "limit" : 20 , "next_cursor" : null , "previous_cursor" : null } } }
Freeze a card PATCH /card-details/{card_id}/freezeSets the card status to blocked. All authorization requests are declined while the card is frozen. The card record and spending history are preserved. Use Unfreeze to restore the card.
Path parameters Request curl -X PATCH "https://api.nuvion.dev/card-details/crd_01HXYZ9012ABCD/freeze" \ -H "Authorization: Bearer $NUVION_API_KEY "
Response { "data" : { "status" : "blocked" , "updated" : 1760434049154 } }
Unfreeze a card PATCH /card-details/{card_id}/unfreezeRestores a frozen card to active status. Subsequent authorization requests are processed normally.
Path parameters Request curl -X PATCH "https://api.nuvion.dev/card-details/crd_01HXYZ9012ABCD/unfreeze" \ -H "Authorization: Bearer $NUVION_API_KEY "
Response { "data" : { "status" : "active" , "updated" : 1760434049154 } }
Reassign a card PATCH /cards/{card_id}/accountMoves the card to a different account. If the target account’s currency differs from the card’s transaction currency, FX conversion is applied automatically at the prevailing rate.
Path parameters Request parameters The ID of the account to reassign the card to.
Request 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": "01K747KD7QW8KQS2GRD8MQBT99" }'
Response { "data" : { "card_id" : "crd_01HXYZ9012ABCD" , "account_id" : "01K747KD7QW8KQS2GRD8MQBT99" } }
Errors Code Description 404The card or target account was not found. 409The card is already assigned to this account.
Delete a card DELETE /card-details/{card_id}Soft-deletes the card. The card is immediately blocked and removed from all listings. The underlying record is retained for audit and transaction history purposes.
Deletion cannot be reversed. A deleted card cannot be reactivated — issue a new card if the cardholder needs continued access.
Path parameters Request curl -X DELETE "https://api.nuvion.dev/card-details/crd_01HXYZ9012ABCD" \ -H "Authorization: Bearer $NUVION_API_KEY "
Response { "data" : { "status" : "blocked" , "deleted" : 1760434049154 } }
