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

# Cards

> One-time virtual cards created against a member's added card, authenticated as the member.

A **card** here is a one-time virtual card Agentcard creates against a card the member has added. Your agent keys its credentials into a checkout, and the card closes itself after its first approved charge (or when you close it).

Every endpoint in this resource is authenticated with the **member's connection token** from [Verify the code](/api-reference/connections/verify), not your platform token.

Start with **flow status**: one read that says what should happen next for this member (add a card, create a card, share an approval link, or fetch the open card).

## The card object

| Field                                | Type    | Description                                                                                                                                                                                                                                                                                                                |
| ------------------------------------ | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `object`                             | string  | `card`                                                                                                                                                                                                                                                                                                                     |
| `id`                                 | string  |                                                                                                                                                                                                                                                                                                                            |
| `status`                             | string  | `approval_pending` (production, until the member approves), `open` (carries credentials), `in_use`, `pausing` (a charge paused the card; the card network has not confirmed yet), `paused`, `closing` (a charge spent the card; the network has not confirmed yet), `closed`. `pausing` and `closing` finish on their own. |
| `spend_limit_cents`, `balance_cents` | integer |                                                                                                                                                                                                                                                                                                                            |
| `connected_card_id`                  | string  | The attachment this card draws on.                                                                                                                                                                                                                                                                                         |
| `last4`, `expiry`                    | string  |                                                                                                                                                                                                                                                                                                                            |
| `approval_url`, `expires_at`         | string  | Only while `approval_pending`.                                                                                                                                                                                                                                                                                             |
| `credentials`                        | object  | Only on an `open` card: number, expiry, CVC to key into a checkout. Never persist it. Each read notifies the member.                                                                                                                                                                                                       |
| `credentials_status`                 | string  | `protected` when the member requires an approval per reveal; `retry` when the read should be retried.                                                                                                                                                                                                                      |
| `closed_reason`                      | string  | Only when `closed`: `used`, `canceled`, `expired`, `declined`.                                                                                                                                                                                                                                                             |

## The flow status object

One read that says what to do next for a member.

| Field            | Type   | Description                                                                                       |
| ---------------- | ------ | ------------------------------------------------------------------------------------------------- |
| `status`         | string | `no_card_attached`, `attach_pending`, `attach_failed`, `ready`, `approval_pending`, `card_ready`. |
| `next_action`    | object | `{ type, id, url, expires_at }`. `url` is the page to hand the member.                            |
| `attached_cards` | array  | The member's added cards: `id`, `status`, `network`, `brand`, `last4`, `art_url`.                 |
| `card`           | object | The open or pending card, when there is one.                                                      |

```json theme={null}
{
  "object": "flow_status",
  "status": "ready",
  "next_action": { "type": "create_card" },
  "attached_cards": [{ "id": "ca_123", "status": "active", "network": "visa", "brand": "Visa", "last4": "4242", "art_url": null }]
}
```

## Endpoints

| Endpoint                             |                                                                                                                                          |
| ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `GET /api/v2/flow_status`            | [Get the member flow status](/api-reference/cards/flow-status)                                                                           |
| `GET /api/v2/cards`                  | [List the member's cards](/api-reference/cards/list)                                                                                     |
| `POST /api/v2/cards`                 | [Create a card](/api-reference/cards/create): sandbox returns an open card, production returns `approval_pending` with an `approval_url` |
| `GET /api/v2/cards/{card_id}`        | [Get a card](/api-reference/cards/get): carries credentials while `open`; each read notifies the member                                  |
| `POST /api/v2/cards/{card_id}/close` | [Close a card](/api-reference/cards/close)                                                                                               |