> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nuvion.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Cards

> Issue virtual and disposable cards, manage spending controls, and view card transactions.

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

<ResponseField name="id" type="string">
  Unique card identifier.
</ResponseField>

<ResponseField name="name" type="string">
  Display name assigned to the card.
</ResponseField>

<ResponseField name="status" type="string">
  Card status. One of `active`, `blocked`, or `fraud`.
</ResponseField>

<ResponseField name="type" type="string">
  Card type. One of `disposable`, `virtual`, or `physical`.
</ResponseField>

<ResponseField name="number" type="string">
  Full card number (PAN). Treat as sensitive — never log or store.
</ResponseField>

<ResponseField name="expiration_month" type="string">
  Card expiration month in `MM` format.
</ResponseField>

<ResponseField name="expiration_year" type="string">
  Card expiration year in `YY` format.
</ResponseField>

<ResponseField name="cvv" type="string">
  Card verification value. Treat as sensitive — never log or store.
</ResponseField>

<ResponseField name="individual_controls" type="object">
  Spending controls and real-time usage tracking. Empty object for disposable cards.

  <Expandable title="individual_controls fields">
    <ResponseField name="billing_cycle" type="string">Billing cycle period. e.g. `"Weekly"`, `"Monthly"`.</ResponseField>
    <ResponseField name="billing_cycle_day" type="string">Day the billing cycle resets. e.g. `"Sunday"`.</ResponseField>
    <ResponseField name="cycle_transaction_count" type="number">Max transactions per billing cycle.</ResponseField>
    <ResponseField name="daily_amount_limit" type="number">Max total spend per day in the smallest currency unit.</ResponseField>
    <ResponseField name="daily_transaction_count" type="number">Max transactions per day.</ResponseField>
    <ResponseField name="transaction_amount_limit" type="number">Max amount per individual transaction in the smallest currency unit.</ResponseField>
    <ResponseField name="amount_used" type="number">Total amount spent this billing cycle.</ResponseField>
    <ResponseField name="amount_hold" type="number">Amount currently on hold (pending authorization).</ResponseField>
    <ResponseField name="amount_balance" type="number">Remaining spendable balance.</ResponseField>
    <ResponseField name="daily_transaction_count_used" type="number">Transactions completed today.</ResponseField>
    <ResponseField name="daily_transaction_count_hold" type="number">Transactions pending today.</ResponseField>
    <ResponseField name="daily_transaction_count_balance" type="number">Remaining transactions allowed today.</ResponseField>
    <ResponseField name="daily_amount_limit_used" type="number">Total amount spent today.</ResponseField>
    <ResponseField name="daily_amount_limit_hold" type="number">Amount on hold today.</ResponseField>
    <ResponseField name="daily_amount_limit_balance" type="number">Remaining daily spend allowance.</ResponseField>
    <ResponseField name="cycle_transaction_count_used" type="number">Transactions completed this billing cycle.</ResponseField>
    <ResponseField name="cycle_transaction_count_hold" type="number">Transactions pending this billing cycle.</ResponseField>
    <ResponseField name="cycle_transaction_count_balance" type="number">Remaining transactions allowed this billing cycle.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="individual_mcc_controls" type="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.
</ResponseField>

<ResponseField name="mcc_group_controls" type="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.
</ResponseField>

<ResponseField name="billing" type="object">
  Billing address on file for the card.

  <Expandable title="billing fields">
    <ResponseField name="address_line_1" type="string">Street address line 1.</ResponseField>
    <ResponseField name="address_line_2" type="string">Street address line 2.</ResponseField>
    <ResponseField name="city" type="string">City.</ResponseField>
    <ResponseField name="state" type="string">State or province.</ResponseField>
    <ResponseField name="postal_code" type="string">ZIP or postal code.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="shipping" type="object">
  Shipping address for physical cards. `null` for virtual and disposable cards. Same shape as `billing`.
</ResponseField>

<ResponseField name="created" type="number">
  Unix timestamp in milliseconds when the card was created.
</ResponseField>

***

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

<ParamField body="account_id" type="string" required>
  The ID of the account to fund the card from.
</ParamField>

<ParamField body="card_name" type="string" required>
  Display name for the card. Used in listings and the dashboard.
</ParamField>

<ParamField body="cardholder" type="object" required>
  Identity details for the cardholder.

  <Expandable title="cardholder fields">
    <ParamField body="first_name" type="string" required>First name.</ParamField>
    <ParamField body="last_name" type="string" required>Last name.</ParamField>
    <ParamField body="email" type="string" required>Email address.</ParamField>
    <ParamField body="phone_number" type="string" required>Phone number in E.164 format. e.g. `+12125550198`.</ParamField>
  </Expandable>
</ParamField>

<ParamField body="currency" type="string" required>
  ISO 4217 currency code for the card. e.g. `USD`.
</ParamField>

<ParamField body="expiration_month" type="string" required>
  Card expiration month in `MM` format. e.g. `"12"`.
</ParamField>

<ParamField body="expiration_year" type="string" required>
  Card expiration year in `YY` format. e.g. `"27"`.
</ParamField>

<ParamField body="metadata" type="object">
  Arbitrary key-value metadata.
</ParamField>

### Request

```bash theme={null}
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.

```json theme={null}
{
  "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

<ParamField body="account_id" type="string" required>
  The ID of the account to fund the card from.
</ParamField>

<ParamField body="card_name" type="string" required>
  Display name for the card.
</ParamField>

<ParamField body="currency" type="string" required>
  ISO 4217 currency code for the card. e.g. `USD`.
</ParamField>

<ParamField body="cardholder" type="object" required>
  Identity details for the cardholder. Same shape as disposable card `cardholder`.
</ParamField>

<ParamField body="individual_controls" type="object">
  General spending controls. All fields are optional.

  <Expandable title="individual_controls fields">
    <ParamField body="billing_cycle" type="string">Billing cycle period. e.g. `"Weekly"`, `"Monthly"`.</ParamField>
    <ParamField body="billing_cycle_day" type="string">Day the billing cycle resets. e.g. `"Sunday"` for a weekly cycle.</ParamField>
    <ParamField body="cycle_transaction_count" type="number">Max transactions per billing cycle.</ParamField>
    <ParamField body="daily_amount_limit" type="number">Max total spend per day in the smallest currency unit.</ParamField>
    <ParamField body="daily_transaction_count" type="number">Max transactions per day.</ParamField>
    <ParamField body="transaction_amount_limit" type="number">Max amount per individual transaction in the smallest currency unit.</ParamField>
  </Expandable>
</ParamField>

<ParamField body="individual_mcc_controls" type="array">
  Per-MCC spending controls. Each entry targets a specific merchant category code.

  <Expandable title="individual_mcc_controls fields">
    <ParamField body="mcc" type="number" required>4-digit Merchant Category Code.</ParamField>
    <ParamField body="open" type="boolean">When `false`, all transactions at this MCC are blocked. Defaults to `true`.</ParamField>
    <ParamField body="amount" type="number">Max cumulative spend for this MCC in the smallest currency unit.</ParamField>
    <ParamField body="cycle_transaction_count" type="number">Max transactions at this MCC per billing cycle.</ParamField>
    <ParamField body="daily_amount_limit" type="number">Max daily spend at this MCC.</ParamField>
    <ParamField body="daily_transaction_count" type="number">Max daily transactions at this MCC.</ParamField>
    <ParamField body="transaction_amount_limit" type="number">Max amount per individual transaction at this MCC.</ParamField>
  </Expandable>
</ParamField>

<ParamField body="mcc_group_controls" type="array">
  Spending controls applied to a named group of MCCs configured in your Nuvion dashboard.

  <Expandable title="mcc_group_controls fields">
    <ParamField body="group_name" type="string" required>Name of the MCC group.</ParamField>
    <ParamField body="open" type="boolean">When `false`, all MCCs in this group are blocked. Defaults to `true`.</ParamField>
    <ParamField body="amount" type="number">Max cumulative spend for this group.</ParamField>
    <ParamField body="cycle_transaction_count" type="number">Max transactions for this group per billing cycle.</ParamField>
    <ParamField body="daily_amount_limit" type="number">Max daily spend for this group.</ParamField>
    <ParamField body="daily_transaction_count" type="number">Max daily transactions for this group.</ParamField>
    <ParamField body="transaction_amount_limit" type="number">Max amount per individual transaction within this group.</ParamField>
  </Expandable>
</ParamField>

<ParamField body="set_alert_service_flag" type="boolean">
  When `true`, enables transaction alerts for this card. Defaults to `false`.
</ParamField>

<ParamField body="metadata" type="object">
  Arbitrary key-value metadata.
</ParamField>

### Request

```bash theme={null}
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.

```json theme={null}
{
  "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

<ParamField query="account_id" type="string">
  Filter by account. If omitted, returns all cards across all accounts for the entity.
</ParamField>

<ParamField query="limit" type="integer">
  Number of results per page. Between 1 and 100. Defaults to `20`.
</ParamField>

<ParamField query="cursor" type="string">
  Pagination cursor for the next page. Use `next_cursor` from the previous response.
</ParamField>

<ParamField query="prev_cursor" type="string">
  Pagination cursor for the previous page. Use `prev_cursor` from the previous response.
</ParamField>

### Request

```bash theme={null}
curl "https://api.nuvion.dev/cards?account_id=01K747KD7QW8KQS2GRD8MQBT55&limit=20" \
  -H "Authorization: Bearer $NUVION_API_KEY"
```

### Response

```json theme={null}
{
  "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.

<Warning>
  This endpoint returns the card `number` and `cvv`. Ensure your server-side code never logs or stores these values.
</Warning>

### Path parameters

<ParamField path="card_id" type="string" required>
  The card ID.
</ParamField>

### Request

```bash theme={null}
curl "https://api.nuvion.dev/card-details/crd_01HXYZ9012ABCD" \
  -H "Authorization: Bearer $NUVION_API_KEY"
```

### Response

Returns the full [Card object](#the-card-object), including credentials and usage tracking.

```json theme={null}
{
  "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

<ParamField path="card_id" type="string" required>
  The card ID.
</ParamField>

### Query parameters

<ParamField query="limit" type="integer">
  Number of results per page. Defaults to `20`.
</ParamField>

<ParamField query="cursor" type="string">
  Cursor for the next page.
</ParamField>

### Request

```bash theme={null}
curl "https://api.nuvion.dev/card-transactions/crd_01HXYZ9012ABCD" \
  -H "Authorization: Bearer $NUVION_API_KEY"
```

### Response

```json theme={null}
{
  "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](#unfreeze-a-card) to restore the card.

### Path parameters

<ParamField path="card_id" type="string" required>
  The card ID.
</ParamField>

### Request

```bash theme={null}
curl -X PATCH "https://api.nuvion.dev/card-details/crd_01HXYZ9012ABCD/freeze" \
  -H "Authorization: Bearer $NUVION_API_KEY"
```

### Response

```json theme={null}
{
  "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

<ParamField path="card_id" type="string" required>
  The card ID.
</ParamField>

### Request

```bash theme={null}
curl -X PATCH "https://api.nuvion.dev/card-details/crd_01HXYZ9012ABCD/unfreeze" \
  -H "Authorization: Bearer $NUVION_API_KEY"
```

### Response

```json theme={null}
{
  "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

<ParamField path="card_id" type="string" required>
  The card ID.
</ParamField>

### Request parameters

<ParamField body="account_id" type="string" required>
  The ID of the account to reassign the card to.
</ParamField>

### Request

```bash theme={null}
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

```json theme={null}
{
  "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.

<Warning>
  Deletion cannot be reversed. A deleted card cannot be reactivated — issue a new card if the cardholder needs continued access.
</Warning>

### Path parameters

<ParamField path="card_id" type="string" required>
  The card ID.
</ParamField>

### Request

```bash theme={null}
curl -X DELETE "https://api.nuvion.dev/card-details/crd_01HXYZ9012ABCD" \
  -H "Authorization: Bearer $NUVION_API_KEY"
```

### Response

```json theme={null}
{
  "data": {
    "status": "blocked",
    "deleted": 1760434049154
  }
}
```