Cards - Nuvion

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

string

Unique card identifier.

string

Display name assigned to the card.

string

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

string

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

string

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

string

Card expiration month in MM format.

string

Card expiration year in YY format.

string

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

object

Spending controls and real-time usage tracking. Empty object for disposable cards.

Show individual_controls fields

string

Billing cycle period. e.g. "Weekly", "Monthly".

string

Day the billing cycle resets. e.g. "Sunday".

number

Max transactions per billing cycle.

number

Max total spend per day in the smallest currency unit.

number

Max transactions per day.

number

Max amount per individual transaction in the smallest currency unit.

number

Total amount spent this billing cycle.

number

Amount currently on hold (pending authorization).

number

Remaining spendable balance.

number

Transactions completed today.

number

Transactions 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 pending this billing cycle.

number

Remaining transactions allowed this billing cycle.

array

Per-MCC spending controls. Each entry includes all limit and usage fields plus mcc and open. Empty array if no MCC controls are set.

array

MCC group spending controls. Each entry includes group_name, open, and applicable limit and usage fields. Empty array if no group controls are set.

object

Billing address on file for the card.

Show billing fields

string

Street address line 1.

string

Street address line 2.

string

City.

string

State or province.

string

ZIP or postal code.

object

Shipping address for physical cards. null for virtual and disposable cards. Same shape as billing.

number

Unix timestamp in milliseconds when the card was created.

Create a disposable card

POST /disposable-cards Issues a single-use virtual card funded from the specified account. The card is automatically blocked after its first successful transaction.

Request parameters

string

required

The ID of the account to fund the card from.

string

required

Display name for the card. Used in listings and the dashboard.

object

required

Identity details for the cardholder.

Show cardholder fields

string

required

First name.

string

required

Last name.

string

required

Email address.

string

required

Phone number in E.164 format. e.g. +12125550198.

string

required

ISO 4217 currency code for the card. e.g. USD.

string

required

Card expiration month in MM format. e.g. "12".

string

required

Card expiration year in YY format. e.g. "27".

object

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",
    "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
`400`	Validation error — a required field is missing or invalid.
`404`	The `account_id` was not found.
`429`	Rate limit exceeded. Response includes `retry_after`, `limit_type`, `current_count`, and `limit`.

Create a virtual card

POST /virtual-cards Issues 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

string

required

The ID of the account to fund the card from.

string

required

Display name for the card.

string

required

ISO 4217 currency code for the card. e.g. USD.

object

required

Identity details for the cardholder. Same shape as disposable card cardholder.

object

General spending controls. All fields are optional.

Show individual_controls fields

string

Billing cycle period. e.g. "Weekly", "Monthly".

string

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

number

Max transactions per billing cycle.

number

Max total spend per day in the smallest currency unit.

number

Max transactions per day.

number

Max 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

4-digit Merchant Category Code.

boolean

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

number

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

number

Max transactions at this MCC per billing cycle.

number

Max daily spend at this MCC.

number

Max daily transactions at this MCC.

number

Max amount per individual transaction at this MCC.

array

Spending controls applied to a named group of MCCs configured in your Nuvion dashboard.

Show mcc_group_controls fields

string

required

Name of the MCC group.

boolean

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

number

Max cumulative spend for this group.

number

Max transactions for this group per billing cycle.

number

Max daily spend for this group.

number

Max daily transactions for this group.

number

Max amount per individual transaction within this group.

boolean

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

object

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",
    "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
`400`	Validation error — a required field is missing or invalid.
`404`	The `account_id` was not found.
`429`	Rate limit exceeded.

List cards

GET /cards Returns a paginated list of cards. Soft-deleted cards are excluded; frozen and blocked cards are included.

Query parameters

string

Filter by account. If omitted, returns all cards across all accounts for the entity.

integer

Number of results per page. Between 1 and 100. Defaults to 20.

string

Pagination cursor for the next page. Use next_cursor from the previous response.

string

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

string

required

The card ID.

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
`403`	The card does not belong to the authenticated entity.
`404`	The 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

string

required

The card ID.

Query parameters

integer

Number of results per page. Defaults to 20.

string

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}/freeze Sets 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

string

required

The card ID.

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}/unfreeze Restores a frozen card to active status. Subsequent authorization requests are processed normally.

Path parameters

string

required

The card ID.

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}/account Moves 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

string

required

The card ID.

Request parameters

string

required

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
`404`	The card or target account was not found.
`409`	The 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

string

required

The card ID.

Request

curl -X DELETE "https://api.nuvion.dev/card-details/crd_01HXYZ9012ABCD" \
  -H "Authorization: Bearer $NUVION_API_KEY"

Response

{
  "data": {
    "status": "blocked",
    "deleted": 1760434049154
  }
}

​The Card object

​Create a disposable card

​Request parameters

​Request

​Response

​Errors

​Create a virtual card

​Request parameters

​Request

​Response

​Errors

​List cards

​Query parameters

​Request

​Response

​Get card details

​Path parameters

​Request

​Response

​Errors

​Get card transactions

​Path parameters

​Query parameters

​Request

​Response

​Freeze a card

​Path parameters

​Request

​Response

​Unfreeze a card

​Path parameters

​Request

​Response

​Reassign a card

​Path parameters

​Request parameters

​Request

​Response

​Errors

​Delete a card

​Path parameters

​Request

​Response

The Card object

Create a disposable card

Request parameters

Request

Response

Errors

Create a virtual card

Request parameters

Request

Response

Errors

List cards

Query parameters

Request

Response

Get card details

Path parameters

Request

Response

Errors

Get card transactions

Path parameters

Query parameters

Request

Response

Freeze a card

Path parameters

Request

Response

Unfreeze a card

Path parameters

Request

Response

Reassign a card

Path parameters

Request parameters

Request

Response

Errors

Delete a card

Path parameters

Request

Response