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

# Card Issuing

> Issue virtual cards for your entities, set granular spending controls, and manage the full card lifecycle from creation to deletion.

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.

<CodeGroup>
  ```bash curl 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": "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"
    }'
  ```
</CodeGroup>

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

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

<ParamField body="cardholder" type="object" required>
  Details of the cardholder to associate with this card.

  <Expandable title="cardholder fields">
    <ParamField body="email" type="string" required>
      The cardholder's email address.
    </ParamField>

    <ParamField body="first_name" type="string" required>
      The cardholder's first name.
    </ParamField>

    <ParamField body="last_name" type="string" required>
      The cardholder's last name.
    </ParamField>

    <ParamField body="phone_number" type="string" required>
      The cardholder's phone number in E.164 format (e.g. `+12125550198`).
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="currency" type="string" required>
  The ISO 4217 currency code for the card. Must be 3 characters (e.g. `USD`).
</ParamField>

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

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

<ParamField body="metadata" type="object">
  Arbitrary key-value pairs you can attach to the card for your own reference. Not used by Nuvion.
</ParamField>

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

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

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

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

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

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

<ResponseField name="expiration_year" type="string">
  Card expiration year (`YY`).
</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 applied to this card. Empty object for disposable cards.
</ResponseField>

<ResponseField name="individual_mcc_controls" type="array">
  MCC-specific spending controls. Empty array for disposable cards.
</ResponseField>

<ResponseField name="mcc_group_controls" type="array">
  MCC group spending controls. Empty array for disposable cards.
</ResponseField>

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

<CodeGroup>
  ```bash curl 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": "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
      }
    }'
  ```
</CodeGroup>

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

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

<ParamField body="currency" type="string" required>
  The ISO 4217 currency code for the card (e.g. `USD`). Must be 3 characters.
</ParamField>

<ParamField body="cardholder" type="object" required>
  Details of the cardholder to associate with this card.

  <Expandable title="cardholder fields">
    <ParamField body="email" type="string" required>
      The cardholder's email address.
    </ParamField>

    <ParamField body="first_name" type="string" required>
      The cardholder's first name.
    </ParamField>

    <ParamField body="last_name" type="string" required>
      The cardholder's last name.
    </ParamField>

    <ParamField body="phone_number" type="string" required>
      The cardholder's phone number in E.164 format.
    </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 pairs for your own reference.
</ParamField>

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

  <Expandable title="individual_controls fields">
    <ParamField body="billing_cycle" type="string">
      The billing cycle period. e.g. `"Weekly"`, `"Monthly"`.
    </ParamField>

    <ParamField body="billing_cycle_day" type="string">
      The day the billing cycle resets. e.g. `"Sunday"` for a weekly cycle.
    </ParamField>

    <ParamField body="cycle_transaction_count" type="number">
      Maximum number of transactions allowed per billing cycle.
    </ParamField>

    <ParamField body="daily_amount_limit" type="number">
      Maximum total spend per day in the smallest currency unit.
    </ParamField>

    <ParamField body="daily_transaction_count" type="number">
      Maximum number of transactions allowed per day.
    </ParamField>

    <ParamField body="transaction_amount_limit" type="number">
      Maximum 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>
      The 4-digit Merchant Category Code to apply controls to.
    </ParamField>

    <ParamField body="open" type="boolean">
      When `false`, transactions at this MCC are blocked entirely. Defaults to `true`.
    </ParamField>

    <ParamField body="amount" type="number">
      Maximum cumulative spend for this MCC in the smallest currency unit.
    </ParamField>

    <ParamField body="cycle_transaction_count" type="number">
      Maximum transactions at this MCC per billing cycle.
    </ParamField>

    <ParamField body="daily_amount_limit" type="number">
      Maximum daily spend at this MCC in the smallest currency unit.
    </ParamField>

    <ParamField body="daily_transaction_count" type="number">
      Maximum daily transactions at this MCC.
    </ParamField>

    <ParamField body="transaction_amount_limit" type="number">
      Maximum 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.

  <Expandable title="mcc_group_controls fields">
    <ParamField body="group_name" type="string" required>
      The name of the MCC group (as configured in your Nuvion dashboard).
    </ParamField>

    <ParamField body="open" type="boolean">
      When `false`, all MCCs in this group are blocked. Defaults to `true`.
    </ParamField>

    <ParamField body="amount" type="number">
      Maximum cumulative spend for this MCC group.
    </ParamField>

    <ParamField body="cycle_transaction_count" type="number">
      Maximum transactions for this MCC group per billing cycle.
    </ParamField>

    <ParamField body="daily_amount_limit" type="number">
      Maximum daily spend for this MCC group.
    </ParamField>

    <ParamField body="daily_transaction_count" type="number">
      Maximum daily transactions for this MCC group.
    </ParamField>

    <ParamField body="transaction_amount_limit" type="number">
      Maximum amount per individual transaction within this MCC group.
    </ParamField>
  </Expandable>
</ParamField>

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

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

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

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

<ResponseField name="number" type="string">
  The full card number (PAN). Treat as sensitive.
</ResponseField>

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

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

<ResponseField name="cvv" type="string">
  Card verification value. Treat as sensitive.
</ResponseField>

<ResponseField name="individual_controls" type="object">
  The resolved spending controls on this card.

  <Expandable title="individual_controls fields">
    <ResponseField name="billing_cycle" type="string">
      The billing cycle period (e.g. `"Weekly"`).
    </ResponseField>

    <ResponseField name="billing_cycle_day" type="string">
      The day the billing cycle resets.
    </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.
    </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.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="individual_mcc_controls" type="array">
  Resolved per-MCC controls. Each entry includes all limit fields plus `mcc` and `open`.
</ResponseField>

<ResponseField name="mcc_group_controls" type="array">
  Resolved MCC group controls. Each entry includes `group_name`, `open`, and applicable limit fields.
</ResponseField>

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

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

<Note>
  If `account_id` is omitted, this endpoint returns all cards across all accounts for the authenticated entity.
</Note>

<CodeGroup>
  ```bash curl theme={null}
  curl -G https://api.nuvion.dev/cards \
    -H "Authorization: Bearer $NUVION_API_KEY" \
    --data-urlencode "account_id=acc_01HXYZ5678EFGHIJKLMNOP" \
    --data-urlencode "limit=20"
  ```
</CodeGroup>

<ParamField body="account_id" type="string">
  Filter cards by account. Must be 26 characters. If omitted, returns all cards for the entity.
</ParamField>

<ParamField body="limit" type="number">
  Number of cards to return per page. Default `20`, maximum `100`.
</ParamField>

<ParamField body="cursor" type="string">
  Cursor for forward pagination. Use the `next_cursor` value from the previous response.
</ParamField>

<ParamField body="prev_cursor" type="string">
  Cursor for backward pagination. Use the `prev_cursor` value from the previous response.
</ParamField>

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

<ResponseField name="data.cards" type="array">
  Array of card summary objects.

  <Expandable title="card fields">
    <ResponseField name="id" type="string">
      Unique identifier for the card.
    </ResponseField>

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

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

    <ResponseField name="created" type="string">
      ISO 8601 timestamp of when the card was created.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="data.pagination" type="object">
  Pagination metadata.

  <Expandable title="pagination fields">
    <ResponseField name="has_next" type="boolean">
      Whether a next page of results exists.
    </ResponseField>

    <ResponseField name="has_previous" type="boolean">
      Whether a previous page of results exists.
    </ResponseField>

    <ResponseField name="next_cursor" type="string">
      Cursor to pass as `cursor` to retrieve the next page. `null` if no next page.
    </ResponseField>

    <ResponseField name="prev_cursor" type="string">
      Cursor to pass as `prev_cursor` to retrieve the previous page. `null` if no previous page.
    </ResponseField>
  </Expandable>
</ResponseField>

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

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

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

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

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

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

<ResponseField name="data.first_name" type="string">
  Cardholder's first name.
</ResponseField>

<ResponseField name="data.last_name" type="string">
  Cardholder's last name.
</ResponseField>

<ResponseField name="data.number" type="string">
  The full card number (PAN). Treat as sensitive.
</ResponseField>

<ResponseField name="data.expiration_month" type="string">
  Card expiration month (`MM`).
</ResponseField>

<ResponseField name="data.expiration_year" type="string">
  Card expiration year (`YY`).
</ResponseField>

<ResponseField name="data.cvv" type="string">
  Card verification value. Treat as sensitive.
</ResponseField>

<ResponseField name="data.individual_controls" type="object">
  Spending controls and real-time usage tracking for this card.

  <Expandable title="individual_controls fields">
    <ResponseField name="billing_cycle" type="string">
      The billing cycle period (e.g. `"Weekly"`).
    </ResponseField>

    <ResponseField name="billing_cycle_day" type="string">
      The day the billing cycle resets.
    </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.
    </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.
    </ResponseField>

    <ResponseField name="amount_used" type="number">
      Total amount spent against the card balance this cycle.
    </ResponseField>

    <ResponseField name="amount_hold" type="number">
      Amount currently on hold (pending authorization).
    </ResponseField>

    <ResponseField name="amount_balance" type="number">
      Remaining spendable balance (loaded amount minus used and held).
    </ResponseField>

    <ResponseField name="daily_transaction_count_used" type="number">
      Number of transactions completed today.
    </ResponseField>

    <ResponseField name="daily_transaction_count_hold" type="number">
      Number of transactions currently 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 currently pending this billing cycle.
    </ResponseField>

    <ResponseField name="cycle_transaction_count_balance" type="number">
      Remaining transactions allowed this billing cycle.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="data.individual_mcc_controls" type="array">
  Per-MCC controls with usage tracking. Each entry includes all limit fields, `_used`, `_hold`, and `_balance` tracking fields, plus `mcc` and `open`.
</ResponseField>

<ResponseField name="data.mcc_group_controls" type="array">
  MCC group controls. Each entry includes `group_name`, `open`, and applicable limit and usage fields.
</ResponseField>

<ResponseField name="data.billing" type="object">
  The billing address on file for this 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 (optional).</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="data.shipping" type="object">
  The shipping address for physical cards. `null` for virtual and disposable cards.

  <Expandable title="shipping fields">
    <ResponseField name="address_line_1" type="string">Street address line 1.</ResponseField>
    <ResponseField name="address_line_2" type="string">Street address line 2 (optional).</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>

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

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

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

<ResponseField name="data.payments" type="array">
  Array of card transaction objects.

  <Expandable title="payment fields">
    <ResponseField name="_id" type="string">Unique transaction identifier.</ResponseField>
    <ResponseField name="amount" type="number">Transaction amount in the smallest currency unit.</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.</ResponseField>
    <ResponseField name="entity_id" type="string">The entity that owns the account.</ResponseField>
    <ResponseField name="counterparty_id" type="string">The merchant or counterparty ID.</ResponseField>
    <ResponseField name="status" type="string">Transaction status (e.g. `pending`, `completed`, `failed`).</ResponseField>
    <ResponseField name="status_reason" type="string">Human-readable reason for the current status. `null` when not applicable.</ResponseField>
    <ResponseField name="narration" type="string">Description of the transaction.</ResponseField>
    <ResponseField name="type" type="string">Direction of the transaction — `debit` or `credit`.</ResponseField>
    <ResponseField name="payment_type" type="string">Payment rail used (e.g. `card`).</ResponseField>
    <ResponseField name="applicable_fee" type="number">Fee charged for this transaction in the smallest currency unit.</ResponseField>

    <ResponseField name="initiator" type="object">
      Details about who or what initiated the transaction.

      <Expandable title="initiator fields">
        <ResponseField name="type" type="string">Initiator type (e.g. `card`).</ResponseField>
        <ResponseField name="id" type="string">The user ID of the initiating cardholder.</ResponseField>
        <ResponseField name="name" type="string">Full name of the initiating cardholder.</ResponseField>
        <ResponseField name="card_id" type="string">The ID of the card used.</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="recipient" type="object">
      Merchant or recipient details.

      <Expandable title="recipient fields">
        <ResponseField name="name" type="string">Merchant or recipient name.</ResponseField>

        <ResponseField name="address" type="object">
          Merchant address.

          <Expandable title="address fields">
            <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>
            <ResponseField name="country" type="string">ISO 3166-1 alpha-2 country code.</ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="meta" type="object">
      Additional metadata from the payment provider.

      <Expandable title="meta fields">
        <ResponseField name="provider_code" type="string">Response code returned by the card network or processor.</ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="deleted" type="boolean">Whether this transaction record has been soft-deleted.</ResponseField>
    <ResponseField name="created" type="number">Unix timestamp in milliseconds when the transaction was created.</ResponseField>
    <ResponseField name="updated" type="number">Unix timestamp in milliseconds when the transaction was last updated.</ResponseField>
    <ResponseField name="version" type="number">Optimistic concurrency version counter for the transaction record.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="data.pagination" type="object">
  Pagination metadata.

  <Expandable title="pagination fields">
    <ResponseField name="order" type="string">Sort order. One of `desc` or `asc`.</ResponseField>
    <ResponseField name="has_next" type="boolean">Whether a next page of results exists.</ResponseField>
    <ResponseField name="limit" type="number">Number of results returned per page.</ResponseField>
    <ResponseField name="has_previous" type="boolean">Whether a previous page of results exists.</ResponseField>
    <ResponseField name="next_cursor" type="string">Cursor for the next page. `null` if no next page.</ResponseField>
    <ResponseField name="previous_cursor" type="string">Cursor for the previous page. `null` if no previous page.</ResponseField>
  </Expandable>
</ResponseField>

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

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

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

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

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

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

<CodeGroup>
  ```bash curl 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": "acc_01HXYZ5678EFGHIJKLMNOP"
    }'
  ```
</CodeGroup>

<ParamField body="account_id" type="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.
</ParamField>

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

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

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

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

**Error codes:** `400 Bad Request`, `401 Unauthorized`, `500 Internal Server Error`.

***

## What's next

<CardGroup cols={3}>
  <Card title="Accounts" icon="building-columns" href="/core-concepts/accounts">
    Understand how accounts are structured and how to fund a card from an entity account.
  </Card>

  <Card title="Accept a Payment" icon="arrow-down-to-line" href="/guides/accept-a-payment">
    Accept inbound payments into entity accounts before loading cards.
  </Card>

  <Card title="Errors" icon="triangle-exclamation" href="/errors">
    Full reference for error codes, error object schema, and resolution guidance.
  </Card>
</CardGroup>