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

# Cards

> Issue virtual cards to your users from your server, authenticated with your platform token.

Give a user a virtual card from your server. You create the card with your [platform token](https://docs.agentcard.com/api-reference/access-tokens/overview.md) and the user's `user_id`, read the number at the checkout, and close the card when it's done.

To let your agent create cards itself, see the [MCP server](https://docs.agentcard.com/tools/mcp.md).

Your credential decides the mode: sandbox credentials issue test cards no real merchant accepts, production credentials issue real ones.

The user has to be [connected](https://docs.agentcard.com/api-reference/connections/overview.md) first, or created by your company with [`POST /api/v2/users`](https://docs.agentcard.com/api-reference/users/create). In production they also need to pass [identity verification](https://docs.agentcard.com/api-reference/identity-verification/overview.md).

## The card object

| Field | Type | Description |
| - | - | - |
| `object` | string | `card` |
| `id` | string | |
| `status` | string | `creating`, `open`, `in_use`, `paused`, `pausing`, `closing`, or `closed`. |
| `type` | string | `single_use` closes after its first approved charge. `multi_use` stays open until its limit is spent. |
| `spend_limit_cents`, `balance_cents` | integer | What the card can spend in all, and what's left. |
| `last4`, `expiry` | string | |
| `user_id` | string | The user the card is for. |
| `cardholder_name`, `billing_address` | string | The name and address a payment form asks for. |
| `funds_source`, `transfer_id` | string | On a new card: what funded it, and the transfer when your company did. |
| `closed_reason` | string | Only when `closed`: `used`, `canceled`, `expired`, `declined`. |
| `card_expires_at` | string | When a `multi_use` card closes itself. |
| `created_at` | string | |

The card object never carries the number or CVC. [Read the credentials](https://docs.agentcard.com/api-reference/cards/credentials.md) for those.

## Fund a card

Your company's funding setting decides where the money comes from. It applies to every card and can't be set per card, so sending `funds_source` answers `400 funds_source_not_supported`. [`GET /api/v2/company_wallet`](https://docs.agentcard.com/api-reference/company-wallet/overview) returns it as `default_funds_source`.

| Setting | Draws on |
| - | - |
| `company_flow` | Your company balance. |
| `onramp_flow` | The user's own balance. |

Check what your company can spend with the [company wallet](https://docs.agentcard.com/api-reference/company-wallet/overview.md). Fund a user's own balance with [`POST /api/v2/wallet/fund`](https://docs.agentcard.com/api-reference/user-balance/fund). Sandbox company-funded cards skip identity verification, so test the `kyc_required` answer in production.

## Use your company's token

Every endpoint here takes your platform token and names the user with `user_id`. A user's connection token is refused:

```json theme={null}
{
  "error": {
    "code": "company_credential_required",
    "message": "This endpoint no longer takes a user's connection token. Call /api/v2/cards with your company's access token and pass user_id.",
    "docs": "https://docs.agentcard.com/api-reference/cards/overview"
  }
}
```

Exchange your client credentials for a [platform token](https://docs.agentcard.com/api-reference/access-tokens/create.md) and send that instead, with the user's id in the request.

## Retry safely

Send an `Idempotency-Key` on every create. A retry with the same key collects the same card and spends once. In sandbox, a card funded from a user's balance ignores the key, so each retry creates another test card.

A company-funded card can take up to a minute to fund. Past that, the create answers `202` with `funding_in_progress`. Wait `retry_after_seconds`, then send the same request with the same key to collect the card. After a timeout, retry with the same key too, so you never issue a second card.


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