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

# Top up a card

> Quote a top-up, reserve funds, and confirm the credited result.

## Required access

Use `cards:read`, `cards:write`, and `operations:read`. Select a card from `GET /api/v1/cards`; its `id` and `productId` belong to your company and environment.

## Quote and submit

Call `POST /api/v1/quotes` with:

```json theme={null}
{"type":"topup","productId":"virtual-usd","amount":"25.00"}
```

Copy the returned `total` into the operation:

```json theme={null}
{"type":"topup","productId":"virtual-usd","cardId":"CARD_ID","amount":"25.00","expectedTotal":"QUOTED_TOTAL"}
```

Send this body to `POST /api/v1/operations` with a unique `Idempotency-Key`. Reuse that key only for retries of this exact request.

## Track completion

Track the operation ID or process its webhook. `completed` confirms the operation; an accepted request only reserves funds. The resulting card balance can differ from the top-up amount because the card may already have funds or spending activity.

Avoid overlapping top-ups on the same card. If an earlier result is unknown, reconcile it first. Never infer success from a timeout, and never turn `manual_review` into a fresh top-up.

## Pricing changes and failures

`QUOTE_CHANGED` means the submitted total no longer matches current pricing. Fetch a new quote and obtain your customer's approval for the new total. `INSUFFICIENT_BALANCE` means available company funds cannot cover the operation, including fees.

Live top-ups require an enabled live card integration. Sandbox top-ups do not move real money.