Card Issuing

Nuvion lets you issue two types of cards on behalf of your entities: disposable single-use cards for one-off payments, and virtual cards for recurring spend. Both card types are funded from an existing entity account and can be reassigned, frozen, unfrozen, or soft-deleted at any time. By the end of this guide you’ll have issued a card and be able to manage it through its full lifecycle.

Card types

Type	Description	Use case
`disposable`	Single-use virtual card. Automatically blocked after the first successful transaction.	Ad-hoc vendor payments, one-time subscriptions
`virtual`	Reusable card for ongoing spend.	Employee expense cards, recurring vendor payments

Supported currencies

Currency	Card issuance
`USD`	Supported

More currencies will be added over time. A card’s funding account doesn’t need to hold the same currency as the card: Nuvion applies FX conversion automatically at the prevailing rate as the card is used.

Card statuses

Status	Description
`active`	Card is in good standing and can be used for transactions.
`blocked`	Card is frozen or has been soft-deleted. No new transactions are authorized.
`fraud`	Card has been flagged for suspected fraud. Contact support to resolve.

A card’s actual spending limit is the available balance on its linked account, not a value set on the card itself. See The Card object for the full field-by-field schema.

Issue a card

Both card types are funded from an account you specify at creation and require a cardholder (the individual who’ll use the card). Card expiration can’t be set more than 2 years out: a later expiration_year/expiration_month is rejected. To issue a single-use card for a one-off payment, use POST /disposable-cards:

curl -X POST https://api.nuvion.dev/disposable-cards \
  -H "Authorization: Bearer $NUVION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "01HQ7K3PXDCVNZFTMGBRY5WSJA",
    "card_name": "Alex Travel Card",
    "cardholder": {
      "email": "alex.johnson@example.com",
      "first_name": "Alex",
      "last_name": "Johnson",
      "phone_number": "+12125550198"
    },
    "currency": "USD",
    "expiration_month": "09",
    "expiration_year": "28"
  }'

To issue a reusable card for ongoing spend, use POST /virtual-cards instead. It accepts the same fields:

curl -X POST https://api.nuvion.dev/virtual-cards \
  -H "Authorization: Bearer $NUVION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "01HQ7K3PXDCVNZFTMGBRY5WSJA",
    "card_name": "Marketing Team Card",
    "currency": "USD",
    "cardholder": {
      "email": "alex.johnson@example.com",
      "first_name": "Alex",
      "last_name": "Johnson",
      "phone_number": "+12125550198"
    },
    "expiration_month": "06",
    "expiration_year": "28"
  }'

Both return the created card with status: "active":

{
  "status": "success",
  "data": {
    "id": "01HXYZ9012ABCDEFGHJKMNPQRS",
    "status": "active",
    "name": "Alex Travel Card",
    "number": "4111111111111234",
    "expiration_month": "09",
    "expiration_year": "28",
    "cvv": "123",
    "individual_controls": {
      "life_time_transaction_count": 1,
      "daily_transaction_count": 1
    },
    "individual_mcc_controls": [],
    "mcc_group_controls": [],
    "created": 1788449757970
  }
}

Save the id. Card credentials (number, cvv) are only returned in this creation response; retrieve them again later via Get card details if needed. See Create a disposable card and Create a virtual card for the full parameter and error reference.

Retrieve cards

List cards for an entity with GET /cards, optionally filtered by account_id:

curl -G https://api.nuvion.dev/cards \
  -H "Authorization: Bearer $NUVION_API_KEY" \
  --data-urlencode "account_id=01HQ7K3PXDCVNZFTMGBRY5WSJA" \
  --data-urlencode "limit=20"

Fetch a single card’s full details, including its number and cvv, with GET /card-details/{card_id}, or its transaction history, including any reversals, with GET /card-transactions/{card_id}.

Get card details returns the card number and cvv. Ensure your server-side code never logs or stores these values.

See List cards, Get card details, and Get card transactions for the full response schema, including how a reversed transaction differs from a regular card debit.

Manage a card

Action	Endpoint	Effect
Freeze	`PATCH /card-details/{card_id}/freeze`	Sets the card to `blocked`. All authorizations are declined. Spending history is preserved.
Unfreeze	`PATCH /card-details/{card_id}/unfreeze`	Restores a frozen card to `active`.
Reassign	`PATCH /cards/{card_id}/account`	Moves the card to a different account owned by the same entity. Nuvion applies FX conversion automatically if the target account’s currency differs from the card’s.
Delete	`DELETE /card-details/{card_id}`	Soft-deletes the card. It’s immediately blocked and removed from listings; the record is retained for audit purposes.

Deletion is not reversible. A deleted card cannot be reactivated. Issue a new card if the cardholder needs continued access.

For example, to freeze a card:

curl -X PATCH https://api.nuvion.dev/card-details/01HXYZ9012ABCDEFGHJKMNPQRS/freeze \
  -H "Authorization: Bearer $NUVION_API_KEY"

See Freeze a card and the other lifecycle endpoints in the API reference for request parameters, response shapes, and errors.

Webhooks

Subscribe to cards.created, cards.frozen, cards.unfrozen, and cards.deleted to track a card’s lifecycle in real time instead of polling Get card details. See Event types for the full payload schema. Actual card transactions aren’t a separate event type; they arrive as the same outflows events used for payouts, distinguished by payment_type:

`payment_type`	Direction	Event
`card-debit`	Debit	`outflows.created` / `outflows.completed` / `outflows.failed`
`card-debit-recoup`	Debit	`outflows.created` / `outflows.completed` / `outflows.failed`
`card-debit-reversal`	Credit	`outflows.refunded`
`card-credit-refund`	Credit	`outflows.refunded`

See outflows.created for the standard debit lifecycle and outflows.refunded for the reversal and refund payload shapes, including card_id and the funding account.

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.

Get Started

Core Concepts

Webhooks

Guides

Card types

Supported currencies

Card statuses

Issue a card

Retrieve cards

Manage a card

Webhooks

What’s next

Accounts

Accept a Payment

Errors

​Card types

​Supported currencies

​Card statuses

​Issue a card

​Retrieve cards

​Manage a card

​Webhooks

​What’s next

Accounts

Accept a Payment

Errors

Card types

Supported currencies

Card statuses

Issue a card

Retrieve cards

Manage a card

Webhooks

What’s next