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

# Using the cards

> Read a card's credentials at checkout, pay with it, and manage it afterwards.

An issued card works like any card: your agent types the number, expiry and CVC into a merchant's checkout. What is different is what happens around it. Credentials are revealed on demand, single-use cards close themselves, and every charge reaches your server as a webhook.

## Read the credentials

Ask for them when the agent is at the payment form, not before:

```json theme={null}
{ "tool": "get_card_details", "arguments": { "card_id": "card_…" } }
```

```json theme={null}
{
  "status": "details",
  "cardId": "card_…",
  "last4": "4832",
  "expiry": "09/29",
  "balanceCents": 2500,
  "cardStatus": "active"
}
```

The full number and CVC are in the tool's text result. Never write them to logs, error reports, or analytics. Prefer `get_card_balance` when you only need the balance.

If the response is `approval_required`, the user has asked to approve each reveal. Show them the prompt, they approve from their own Agentcard session or the emailed link, and your agent retries with the `approval_id`.

## Pay

Type the credentials into the checkout. The card authorizes up to its `amount_cents`, and declines anything above it or outside a merchant lock. Your server receives `transaction.authorized` when money moves and `approval.requested` when a purchase needs a human first.

For merchants Agentcard already covers, your agent can skip the browser: the `buy` tool on the same MCP connection runs the purchase conversationally and pays with the card. See the [Purchase API](/vault/integrations/ecommerce-apis/purchase-api).

## What happens after a charge

* **Single-use cards** close themselves after the first approved charge. `closed_reason` is `used`.
* **Multi-use cards** stay open until their limit is spent or you close them.
* **Refunds** post back to the card that paid. The balance returns to the user.
* **Tokenback:** settled spend earns tokens, 1 token per cent. `get_rewards` shows them, `redeem_rewards` turns them into spending power.

## Manage a card

Multi-use cards can be managed while open:

| Tool                | Does                                                            |
| ------------------- | --------------------------------------------------------------- |
| `pause_card`        | Blocks all new charges. Reversible.                             |
| `resume_card`       | Unblocks a paused card.                                         |
| `update_card_limit` | Resizes the total limit. Raising it draws on the balance.       |
| `close_card`        | Permanent. Returns the unspent balance to the user. Idempotent. |

`list_cards` shows every card the connection can see, with test cards flagged.

## Webhooks

Register a [webhook endpoint](/api-reference/webhook-endpoints/overview) and subscribe to what you need:

| Event                           | Fires when                                      |
| ------------------------------- | ----------------------------------------------- |
| `card.created`                  | A card was issued.                              |
| `transaction.authorized`        | A charge was approved on a card.                |
| `approval.requested`            | A purchase or a reveal is waiting for the user. |
| `user_wallet.funded`            | A deposit landed as spending power.             |
| `identity.verification.updated` | KYC status changed.                             |

React to webhooks, not to the conversation. The agent saying it paid is a claim. `transaction.authorized` is a fact.

## Sandbox

Test cards are issued instantly, carry credentials, and are not accepted by real merchants. Use them to exercise your agent's checkout code against a test storefront such as [shop.agentcard.sh](https://shop.agentcard.sh) on Stripe test mode. The reveal, close and webhook flows are identical to live.