> ## 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](/docs/cli/identity), 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](/docs/identity/cards) for the model and the [Cards API](/docs/api/cards) 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`.