Card Issuing

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
`disposable`	Single-use virtual card. Automatically blocked after the first successful transaction.	Ad-hoc vendor payments, one-time subscriptions
`virtual`	Reusable card with optional spending controls (limits by amount, transaction count, MCC).	Employee expense cards, recurring vendor payments
`physical`	Physical card issued and mailed to the cardholder. Managed via the same card endpoints.	Consumer wallets, debit card programs

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.

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",
    "expiration_month": "12",
    "expiration_year": "27"
  }'

string

required

The ID of the account to fund the card from. Must be 26 characters.

string

required

A display name for the card. Used to identify the card in listings and the dashboard.

object

required

Details of the cardholder to associate with this card.

Show cardholder fields

string

required

The cardholder’s email address.

string

required

The cardholder’s first name.

string

required

The cardholder’s last name.

string

required

The cardholder’s phone number in E.164 format (e.g. +12125550198).

string

required

The ISO 4217 currency code for the card. Must be 3 characters (e.g. USD).

string

required

The card expiration month in MM format (e.g. "12").

string

required

The card expiration year in YY format (e.g. "27").

object

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": []
  }
}

string

Card status. One of active, blocked, or fraud.

string

Unique identifier for the card.

string

The display name assigned to the card.

string

The full card number (PAN). Treat as sensitive — never log or store.

string

Card expiration month (MM).

string

Card expiration year (YY).

string

Card verification value. Treat as sensitive — never log or store.

object

Spending controls applied to this card. Empty object for disposable cards.

array

MCC-specific spending controls. Empty array for disposable cards.

array

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",
    "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
    }
  }'

string

required

The ID of the account to fund the card from. Must be 26 characters.

string

required

A display name for the card.

string

required

The ISO 4217 currency code for the card (e.g. USD). Must be 3 characters.

object

required

Details of the cardholder to associate with this card.

Show cardholder fields

string

required

The cardholder’s email address.

string

required

The cardholder’s first name.

string

required

The cardholder’s last name.

string

required

The cardholder’s phone number in E.164 format.

boolean

When true, enables transaction alerts for this card. Defaults to false.

object

Arbitrary key-value pairs for your own reference.

object

General spending controls applied to this card. All fields are optional.

Show individual_controls fields

string

The billing cycle period. e.g. "Weekly", "Monthly".

string

The day the billing cycle resets. e.g. "Sunday" for a weekly cycle.

number

Maximum number of transactions allowed per billing cycle.

number

Maximum total spend per day in the smallest currency unit.

number

Maximum number of transactions allowed per day.

number

Maximum amount per individual transaction in the smallest currency unit.

array

Per-MCC spending controls. Each entry targets a specific merchant category code.

Show individual_mcc_controls fields

number

required

The 4-digit Merchant Category Code to apply controls to.

boolean

When false, transactions at this MCC are blocked entirely. Defaults to true.

number

Maximum cumulative spend for this MCC in the smallest currency unit.

number

Maximum transactions at this MCC per billing cycle.

number

Maximum daily spend at this MCC in the smallest currency unit.

number

Maximum daily transactions at this MCC.

number

Maximum amount per individual transaction at this MCC.

array

Spending controls applied to a named group of MCCs.

Show mcc_group_controls fields

string

required

The name of the MCC group (as configured in your Nuvion dashboard).

boolean

When false, all MCCs in this group are blocked. Defaults to true.

number

Maximum cumulative spend for this MCC group.

number

Maximum transactions for this MCC group per billing cycle.

number

Maximum daily spend for this MCC group.

number

Maximum daily transactions for this MCC group.

number

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

string

Card status. One of active, blocked, or fraud.

string

Unique identifier for the card.

string

The display name assigned to the card.

string

The full card number (PAN). Treat as sensitive.

string

Card expiration month (MM).

string

Card expiration year (YY).

string

Card verification value. Treat as sensitive.

object

The resolved spending controls on this card.

Show individual_controls fields

string

The billing cycle period (e.g. "Weekly").

string

The day the billing cycle resets.

number

Max transactions per billing cycle.

number

Max total spend per day.

number

Max transactions per day.

number

Max amount per individual transaction.

array

Resolved per-MCC controls. Each entry includes all limit fields plus mcc and open.

array

Resolved MCC group controls. Each entry includes group_name, open, and applicable limit fields.

number

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"

string

Filter cards by account. Must be 26 characters. If omitted, returns all cards for the entity.

number

Number of cards to return per page. Default 20, maximum 100.

string

Cursor for forward pagination. Use the next_cursor value from the previous response.

string

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

Array of card summary objects.

Show card fields

string

Unique identifier for the card.

string

Display name of the card.

string

Card status. One of active, blocked, or fraud.

string

ISO 8601 timestamp of when the card was created.

object

Pagination metadata.

Show pagination fields

boolean

Whether a next page of results exists.

boolean

Whether a previous page of results exists.

string

Cursor to pass as cursor to retrieve the next page. null if no next page.

string

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

string

Card status. One of active, blocked, or fraud.

string

Unique identifier for the card.

string

Card type. One of disposable, virtual, or physical.

string

Cardholder’s first name.

string

Cardholder’s last name.

string

The full card number (PAN). Treat as sensitive.

string

Card expiration month (MM).

string

Card expiration year (YY).

string

Card verification value. Treat as sensitive.

object

Spending controls and real-time usage tracking for this card.

Show individual_controls fields

string

The billing cycle period (e.g. "Weekly").

string

The day the billing cycle resets.

number

Max transactions per billing cycle.

number

Max total spend per day.

number

Max transactions per day.

number

Max amount per individual transaction.

number

Total amount spent against the card balance this cycle.

number

Amount currently on hold (pending authorization).

number

Remaining spendable balance (loaded amount minus used and held).

number

Number of transactions completed today.

number

Number of transactions currently pending today.

number

Remaining transactions allowed today.

number

Total amount spent today.

number

Amount on hold today.

number

Remaining daily spend allowance.

number

Transactions completed this billing cycle.

number

Transactions currently pending this billing cycle.

number

Remaining transactions allowed this billing cycle.

array

Per-MCC controls with usage tracking. Each entry includes all limit fields, _used, _hold, and _balance tracking fields, plus mcc and open.

array

MCC group controls. Each entry includes group_name, open, and applicable limit and usage fields.

object

The billing address on file for this card.

Show billing fields

string

Street address line 1.

string

Street address line 2 (optional).

string

City.

string

State or province.

string

ZIP or postal code.

object

The shipping address for physical cards. null for virtual and disposable cards.

Show shipping fields

string

Street address line 1.

string

Street address line 2 (optional).

string

City.

string

State or province.

string

ZIP or postal code.

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

Array of card transaction objects.

Show payment fields

string

Unique transaction identifier.

number

Transaction amount in the smallest currency unit.

string

ISO 4217 currency code.

string

Unique idempotency reference for the transaction.

string

The account that was debited.

string

The entity that owns the account.

string

The merchant or counterparty ID.

string

Transaction status (e.g. pending, completed, failed).

string

Human-readable reason for the current status. null when not applicable.

string

Description of the transaction.

string

Direction of the transaction — debit or credit.

string

Payment rail used (e.g. card).

number

Fee charged for this transaction in the smallest currency unit.

object

Details about who or what initiated the transaction.

Show initiator fields

string

Initiator type (e.g. card).

string

The user ID of the initiating cardholder.

string

Full name of the initiating cardholder.

string

The ID of the card used.

object

Merchant or recipient details.

Show recipient fields

string

Merchant or recipient name.

object

Merchant address.

Show address fields

string

City.

string

State or province.

string

ZIP or postal code.

string

ISO 3166-1 alpha-2 country code.

object

Additional metadata from the payment provider.

Show meta fields

string

Response code returned by the card network or processor.

boolean

Whether this transaction record has been soft-deleted.

number

Unix timestamp in milliseconds when the transaction was created.

number

Unix timestamp in milliseconds when the transaction was last updated.

number

Optimistic concurrency version counter for the transaction record.

object

Pagination metadata.

Show pagination fields

string

Sort order. One of desc or asc.

boolean

Whether a next page of results exists.

number

Number of results returned per page.

boolean

Whether a previous page of results exists.

string

Cursor for the next page. null if no next page.

string

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"
  }'

string

required

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.

Get Started

Core Concepts

Webhooks

Guides

Card types

Card statuses

Create a disposable card

Create a virtual card

List cards

Get card details

Get card transactions

Manage a card

Freeze a card

Unfreeze a card

Reassign card to a different account

Delete a card

What’s next

Accounts

Accept a Payment

Errors

​Card types

​Card statuses

​Create a disposable card

​Create a virtual card

​List cards

​Get card details

​Get card transactions

​Manage a card

​Freeze a card

​Unfreeze a card

​Reassign card to a different account

​Delete a card

​What’s next

Accounts

Accept a Payment

Errors

Card types

Card statuses

Create a disposable card

Create a virtual card

List cards

Get card details

Get card transactions

Manage a card

Freeze a card

Unfreeze a card

Reassign card to a different account

Delete a card

What’s next