Cards - Nuvion

Cards are funded from an entity account and can be issued as single-use disposable cards or reusable virtual cards. All cards are managed through the same lifecycle endpoints: freeze, unfreeze, reassign, and delete.

The Card object

string

Unique card identifier.

string

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

string

Display name assigned to the card. Submitted as card_name in the request.

string

Card type. One of disposable or virtual.

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.

string

Cardholder’s first name. Present on Get card details.

string

Cardholder’s last name. Present on Get card details.

number

A placeholder value in the smallest currency unit. Present on Get card details. Not the card’s spending limit: the amount a card can actually transact is the available balance on its linked account.

string

ISO 4217 currency code for the card. Present on Get card details.

object

Spending controls on this card.

Show individual_controls fields

number

Maximum number of transactions allowed over the card’s lifetime.

number

Maximum number of transactions allowed per day.

array

Per-MCC spending controls. Returned as an empty array.

array

Spending controls for a named group of MCCs. Returned as an empty array.

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. Always null.

number

Unix timestamp in milliseconds when the card was created. Present on card creation responses.

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. The account’s currency doesn’t need to match the card’s currency: FX conversion is applied automatically at the prevailing rate as the card is used.

string

required

Display name for the card. Used in listings and the dashboard. Returned as name in the response.

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. See Supported currencies.

string

required

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

string

required

Card expiration year in YY format. e.g. "27". Must be no more than 2 years from the creation date. Requests for a later date are rejected.

string

The ID of the entity to issue this card for. Defaults to the authenticating entity when omitted. Required when acting on a child entity. See Managing child entities for details.

Request

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

Response

Returns the created card object with status: "active". Card credentials (number, cvv) are included in the creation response only.

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

Errors

Code	Description
`401`	Missing or invalid API key.
`404`	The `account_id` was not found.

Create a virtual card

POST /virtual-cards Issues a reusable virtual card. Unlike disposable cards, virtual cards aren’t blocked after a single transaction and support a higher lifetime transaction count.

Request parameters

string

required

string

required

Display name for the card. Returned as name in the response.

string

required

ISO 4217 currency code for the card. See Supported currencies.

object

required

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

string

required

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

string

required

Card expiration year in YY format. e.g. "27". Must be no more than 2 years from the creation date. Requests for a later date are rejected.

string

The ID of the entity to issue this card for. Defaults to the authenticating entity when omitted. Required when acting on a child entity. See Managing child entities for details.

Request

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

Response

Returns the created card object. Card credentials (number, cvv) are included in the creation response only.

{
  "status": "success",
  "data": {
    "id": "01HXYZ9012ABCDEFGHJKMNPQRS",
    "status": "active",
    "name": "Marketing Team Card",
    "number": "4111111111111234",
    "expiration_month": "06",
    "expiration_year": "28",
    "cvv": "123",
    "individual_controls": {
      "life_time_transaction_count": 5000,
      "daily_transaction_count": 100
    },
    "individual_mcc_controls": [],
    "mcc_group_controls": [],
    "created": 1788449735532
  }
}

Errors

Code	Description
`401`	Missing or invalid API key.
`404`	The `account_id` was not found.

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.

string

Defaults to the authenticating entity when omitted. Required when acting on a child entity. See Managing child entities for details.

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 previous_cursor from the previous response.

Request

curl "https://api.nuvion.dev/cards?account_id=01HXYZ0054ABCDEFGHJKMNPQRS&limit=20" \
  -H "Authorization: Bearer $NUVION_API_KEY"

Response

array

Array of card summary objects.

Show card fields

string

Unique identifier for the card.

string

Display name of the card.

string

Card type. One of disposable or virtual.

string

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

string

ISO 4217 currency code for the card.

string

Display name of the account the card is funded from.

string

Date the card was created, as YYYY-MM-DD.

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

{
  "status": "success",
  "data": {
    "cards": [
      {
        "id": "01HXYZ9012ABCDEFGHJKMNPQRS",
        "name": "Marketing Team Card",
        "type": "virtual",
        "status": "active",
        "currency": "USD",
        "nuvion_account_name": "Marketing USD",
        "created": "2026-01-15"
      }
    ],
    "pagination": {
      "order": "desc",
      "has_next": false,
      "limit": 20,
      "has_previous": false,
      "next_cursor": null,
      "previous_cursor": null
    }
  }
}

Errors

Code	Description
`401`	Missing or invalid API key.

Get card details

GET /card-details/{card_id} Returns full details for a single card, including sensitive credentials.

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.

Query parameters

string

Defaults to the authenticating entity when omitted. Required when acting on a child entity. See Managing child entities for details.

Request

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

Response

Returns the full Card object, plus first_name, last_name, amount, and currency.

{
  "status": "success",
  "data": {
    "id": "01HXYZ9012ABCDEFGHJKMNPQRS",
    "status": "active",
    "name": "Marketing Team Card",
    "type": "virtual",
    "number": "4111111111111234",
    "expiration_month": "06",
    "expiration_year": "28",
    "cvv": "123",
    "first_name": "Alex",
    "last_name": "Johnson",
    "amount": 1000000,
    "currency": "USD",
    "individual_controls": {
      "life_time_transaction_count": 5000,
      "daily_transaction_count": 100
    },
    "individual_mcc_controls": [],
    "mcc_group_controls": [],
    "retrieved": 1788451762935,
    "billing": {
      "address_line_1": "350 Fifth Avenue",
      "address_line_2": "Suite 4100",
      "city": "New York",
      "state": "NY",
      "postal_code": "10001"
    }
  }
}

Errors

Code	Description
`401`	Missing or invalid API key.
`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.

string

Defaults to the authenticating entity when omitted. Required when acting on a child entity. See Managing child entities for details.

Request

curl "https://api.nuvion.dev/card-transactions/01HXYZ9012ABCDEFGHJKMNPQRS" \
  -H "Authorization: Bearer $NUVION_API_KEY"

Response

array

Array of card transaction objects.

Show payment fields

string

Unique transaction identifier.

number

Transaction amount in the smallest currency unit. 728 =

7.28 USD.</ResponseField> <ResponseField name="currency" type="string">ISO 4217 currency code.</ResponseField> <ResponseField name="unique_reference" type="string">Unique idempotency reference for the transaction.</ResponseField> <ResponseField name="account_id" type="string">The account that was debited or credited.</ResponseField> <ResponseField name="entity_id" type="string">The entity that owns the account.</ResponseField> <ResponseField name="counterparty_id" type="string">Synthetic counterparty ID for the card network, in the form `acct-{account_id}-card-debit` (or `-card-debit-reversal` for a reversal).</ResponseField> <ResponseField name="status" type="string">Transaction status (e.g. `successful`).</ResponseField> <ResponseField name="aml_status" type="string">AML screening status assigned to the transaction (e.g. `new`).</ResponseField> <ResponseField name="status_reason" type="string">Human-readable explanation for the transaction status.</ResponseField> <ResponseField name="narration" type="string">Description of the transaction.</ResponseField> <ResponseField name="type" type="string">Direction of the transaction. `outflow` for a card debit, `inflow` for a reversal.</ResponseField> <ResponseField name="payment_type" type="string">Payment type. One of `card-debit` or `card-debit-reversal`.</ResponseField> <ResponseField name="applicable_fee" type="number">Fee charged for this transaction in the smallest currency unit. `100` =

1.00 USD.

object

The account that initiated the transaction.

Show initiator fields

string

Initiator type. account for card transactions.

string

The ID of the initiating account.

string

Display name of the initiating account.

string

The ID of the card used.

object

For a card debit, the merchant that was paid. For a reversal, the account the funds were returned to.

Show recipient fields

string

Merchant or account display name.

string

Present only on reversals. account.

string

Present only on reversals. The ID of the account credited.

object

Present only for merchant recipients (not reversals).

Show address fields

string

City.

string

State or province.

string

ZIP or postal code.

string

Country, as returned by the card network. Not always ISO 3166-1 alpha-2.

object

Provider-specific metadata. Field set varies by payment_type.

Show meta fields

string

Card processor code.

string

Processor’s reference for the transaction. null on some reversals.

string

Present only on reversals. What triggered the reversal, e.g. card_payment_reversal.

string

Present only on reversals. The _id of the original transaction being reversed.

boolean

Present only on reversals. Whether the reversal covers part of the original amount.

number

Unix timestamp in milliseconds when the transaction record was soft-deleted, or 0 if not 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.

{
  "status": "success",
  "data": {
    "payments": [
      {
        "_id": "01HXYZ0055ABCDEFGHJKMNPQRS",
        "amount": 728,
        "currency": "USD",
        "unique_reference": "TXN-2026-0001-reversal",
        "account_id": "01HXYZ0054ABCDEFGHJKMNPQRS",
        "entity_id": "01HXYZ0056ABCDEFGHJKMNPQRS",
        "counterparty_id": "acct-01HXYZ0054ABCDEFGHJKMNPQRS-card-debit-reversal",
        "status": "successful",
        "aml_status": "new",
        "status_reason": "card_payment_reversed",
        "narration": "REVERSAL | TXN-2026-0001",
        "type": "inflow",
        "payment_type": "card-debit-reversal",
        "applicable_fee": 0,
        "initiator": {
          "type": "account",
          "id": "01HXYZ0054ABCDEFGHJKMNPQRS",
          "name": "Marketing USD",
          "card_id": "01HXYZ9012ABCDEFGHJKMNPQRS"
        },
        "recipient": {
          "type": "account",
          "id": "01HXYZ0054ABCDEFGHJKMNPQRS",
          "name": "Marketing USD"
        },
        "meta": {
          "source": "card_payment_reversal",
          "source_payment_id": "01HXYZ0057ABCDEFGHJKMNPQRS",
          "provider_reference": null,
          "providerCode": "crp",
          "is_partial_refund": false
        },
        "deleted": 0,
        "created": 1788190603700,
        "updated": 1788190603720,
        "version": 0
      },
      {
        "_id": "01HXYZ0057ABCDEFGHJKMNPQRS",
        "amount": 728,
        "currency": "USD",
        "unique_reference": "TXN-2026-0001",
        "account_id": "01HXYZ0054ABCDEFGHJKMNPQRS",
        "entity_id": "01HXYZ0056ABCDEFGHJKMNPQRS",
        "counterparty_id": "acct-01HXYZ0054ABCDEFGHJKMNPQRS-card-debit",
        "status": "successful",
        "aml_status": "new",
        "status_reason": "Payment approved and processed",
        "narration": "Payment to Acme Corp for 7.28 USD",
        "type": "outflow",
        "payment_type": "card-debit",
        "applicable_fee": 0,
        "initiator": {
          "type": "account",
          "id": "01HXYZ0054ABCDEFGHJKMNPQRS",
          "name": "Marketing USD",
          "card_id": "01HXYZ9012ABCDEFGHJKMNPQRS"
        },
        "recipient": {
          "name": "Acme Corp",
          "address": {
            "city": "San Francisco",
            "state": "CA",
            "postal_code": "94105",
            "country": "US"
          }
        },
        "meta": {
          "providerCode": "crp",
          "provider_reference": "437V23G9X3-2026-07-16 12:14:04-799543"
        },
        "deleted": 0,
        "created": 1788190545125,
        "updated": 1788190603747,
        "version": 0
      }
    ],
    "pagination": {
      "order": "desc",
      "has_next": false,
      "limit": 20,
      "has_previous": false,
      "next_cursor": null,
      "previous_cursor": null
    }
  }
}

Errors

Code	Description
`401`	Missing or invalid API key.
`404`	The card was not found.

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 parameters

string

Defaults to the authenticating entity when omitted. Required when acting on a child entity. See Managing child entities for details.

Request

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

Response

{
  "status": "success",
  "data": {
    "message": "Card frozen successfully",
    "status": "blocked",
    "updated": 1788450426071
  }
}

Errors

Code	Description
`401`	Missing or invalid API key.
`404`	The card was not found.

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 parameters

string

Defaults to the authenticating entity when omitted. Required when acting on a child entity. See Managing child entities for details.

Request

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

Response

{
  "status": "success",
  "data": {
    "message": "Card unfrozen successfully",
    "status": "active",
    "updated": 1788450492520
  }
}

Errors

Code	Description
`401`	Missing or invalid API key.
`404`	The card was not found.

Reassign a card

PATCH /cards/{card_id}/account Moves the card to a different account owned by the same entity. 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.

string

Defaults to the authenticating entity when omitted. Required when acting on a child entity. See Managing child entities for details.

Request

curl -X PATCH "https://api.nuvion.dev/cards/01HXYZ9012ABCDEFGHJKMNPQRS/account" \
  -H "Authorization: Bearer $NUVION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "account_id": "01HXYZ0058ABCDEFGHJKMNPQRS" }'

Response

{
  "status": "success",
  "data": {
    "card_id": "01HXYZ9012ABCDEFGHJKMNPQRS",
    "account_id": "01HXYZ0058ABCDEFGHJKMNPQRS"
  }
}

Errors

Code	Description
`401`	Missing or invalid API key.
`404`	The card or target account was not found, or the target account isn’t accessible by this entity.
`409`	The card is already assigned to this account. Returns “A record with this account_id already exists. Please use different details or check your existing records.”

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 parameters

string

Defaults to the authenticating entity when omitted. Required when acting on a child entity. See Managing child entities for details.

Request

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

Response

{
  "status": "success",
  "data": {
    "message": "Card soft-deleted successfully",
    "status": "blocked",
    "deleted": 1788450644896
  }
}

Errors

Code	Description
`401`	Missing or invalid API key.
`404`	The card was not found.

​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

​Errors

​Get card details

​Path parameters

​Query parameters

​Request

​Response

​Errors

​Get card transactions

​Path parameters

​Query parameters

​Request

​Response

​Errors

​Freeze a card

​Path parameters

​Request parameters

​Request

​Response

​Errors

​Unfreeze a card

​Path parameters

​Request parameters

​Request

​Response

​Errors

​Reassign a card

​Path parameters

​Request parameters

​Request

​Response

​Errors

​Delete a card

​Path parameters

​Request parameters

​Request

​Response

​Errors

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

Errors

Get card details

Path parameters

Query parameters

Request

Response

Errors

Get card transactions

Path parameters

Query parameters

Request

Response

Errors

Freeze a card

Path parameters

Request parameters

Request

Response

Errors

Unfreeze a card

Path parameters

Request parameters

Request

Response

Errors

Reassign a card

Path parameters

Request parameters

Request

Response

Errors

Delete a card

Path parameters

Request parameters

Request

Response

Errors