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

# vetta identity card

> Buy prepaid virtual cards for a persona, reveal their credentials, and log spend.

Cards belong to a [persona](https://vetta.sh/docs/cli/identity.md), so every command takes `--identity`. Reached as `vetta identity card <command>` — three words, where `card` is a sub-group rather than a positional argument. See [Cards](https://vetta.sh/docs/identity/cards.md) for the model and the [Cards API](https://vetta.sh/docs/api/cards.md) for the wire shapes.

`--usd` takes a decimal such as `50` or `12.99`; the CLI converts once to the integer micro-USD the API speaks (`50` → `50000000`).

## Commands

| Command | Description |
| - | - |
| `vetta identity card list` | List the persona's cards (never a credential). |
| `vetta identity card quote` | Price a load before buying. |
| `vetta identity card issue` | Buy a prepaid card (debits credits); `--wait` for it to settle. |
| `vetta identity card show` | Read one card. |
| `vetta identity card reveal` | Reveal a card's number and PIN — audited; needs `--i-understand-this-is-audited`. |
| `vetta identity card retry` | Re-run issuance for a failed card. |
| `vetta identity card cancel` | Mark an active card cancelled. |
| `vetta identity card refund` | Return the credits of a failed card. |
| `vetta identity card transactions` | List a card's logged spend. |
| `vetta identity card spend` | Log a spend against a card. |

`--identity` takes either an `idn_` id or the persona's name; the API resolves both. On a deployment with no card issuer bound, `quote`, `issue`, `retry` and `reveal` answer `501 feature_not_configured`. There is no assign/unassign: an agent whose session selects the persona holds its cards.

## list / quote / issue

```bash theme={"system"}
vetta identity card list --identity ava --status active
vetta identity card quote --identity ava --usd 50
vetta identity card issue --identity ava --label Ads --usd 50 --wait
```

| Flag | Description |
| - | - |
| `--status` | Filter `list`: `pending_payment`, `issuing`, `active`, `failed`, `cancelled` or `refunded`. |
| `--usd` | The load (required on `quote` and `issue`); the quote reports the allowed range and the price. |
| `--label` | A name for the card (required on `issue`). |
| `--wait` | On `issue`: poll the card once a second (up to 30 s) until it leaves `pending_payment` / `issuing`. |
| `--limit` / `--after` | Pagination. |

`issue` debits the quoted price from the organization's credits before anything is ordered; a short balance answers `402 insufficient_credits`. Without `--wait` the card is printed as issued — usually `issuing` — and `show` reads it again.

```json theme={"system"}
{
  "id": "vcd_01j9x2k3m4n5p6q7r8s9t0v1w2",
  "object": "card",
  "status": "active",
  "label": "Ads",
  "brand": "Visa",
  "last4": "4242",
  "load_micro_usd": 50000000,
  "spent_micro_usd": 0,
  "…": "…"
}
```

## show / reveal / retry / cancel / refund

```bash theme={"system"}
vetta identity card show --identity ava --card vcd_…
vetta identity card reveal --identity ava --card vcd_… --i-understand-this-is-audited
vetta identity card retry --identity ava --card vcd_…
vetta identity card cancel --identity ava --card vcd_…
vetta identity card refund --identity ava --card vcd_…
```

| Flag | Description |
| - | - |
| `--card` | The `vcd_` id (required). |
| `--i-understand-this-is-audited` | Required on `reveal`; without it the command refuses before any request is made. |

`reveal` is the only command that prints a card number; every call is recorded as `card.credentials_revealed`, and a card that is not `active` answers `404 not_found`. A lifecycle action from the wrong status answers `state_conflict`. A prepaid card cannot be topped up — issue another.

## transactions / spend

```bash theme={"system"}
vetta identity card transactions --identity ava --card vcd_…
vetta identity card spend --identity ava --card vcd_… --usd 12.99 --merchant "Example Ads" --description "Campaign #4"
```

| Flag | Description |
| - | - |
| `--card` | The `vcd_` id (required). |
| `--usd` | The amount spent (required on `spend`). |
| `--merchant` / `--description` | Optional context for the entry. |
| `--limit` / `--after` | Pagination. |

Logging a spend that would exceed the card's load is refused with `validation_failed`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.