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

# Top Up a Card

> Fund a card from your Visa or Mastercard balance

Once a card is `active`, you can top it up from your `cards_visa` or `cards_mastercard` balance, as long as its card product is reloadable (`is_reloadable: true`).

## Request

```bash theme={null}
curl -X POST https://api.kemycard.com/v1/cards/c1d2e3f4-.../topup \
  -H "Authorization: Bearer sk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount": 100.00}'
```

## Response

The call returns `202`: the top-up is accepted and applied asynchronously.

```json theme={null}
{
  "success": true,
  "data": {
    "card_code": "c1d2e3f4-...",
    "status": "pending",
    "amount": 100.00,
    "fee": 5.00,
    "total_charged": 105.00,
    "currency": "USD"
  }
}
```

## How it works

1. `total_charged` (the amount plus the service fee of the card product) is debited from your ops balance — `cards_mastercard` or `cards_visa`, depending on the card's brand.
2. The card is credited with `amount`.
3. You receive a `card.topup.completed` webhook once the card is credited.
4. If the top-up cannot be applied, you receive `card.topup.failed` and `total_charged` is refunded to the same `cards_visa` or `cards_mastercard` balance.

## Fees

The service fee comes from the card product (`GET /cards/products`): `service_fee_percent` of the amount, with a minimum of `service_fee_min`. The `_with_kyc` values apply when the customer's KYC is approved.

Example with a 5% fee and a 5 USD minimum: a 100 USD top-up costs 105 USD, a 40 USD top-up costs 45 USD.

## Requirements

* Card must be `active` (not frozen, pending, cancelled or failed)
* Card product must be reloadable
* Amount must be between the product's `min_reload` and `max_reload`
* The card balance after the top-up must not exceed the product's `max_balance`
* Your `cards_visa` or `cards_mastercard` balance must cover `total_charged`

## Common errors

| HTTP | Code | When |
| - | - | - |
| 400 | `INSUFFICIENT_BALANCE` | Not enough funds in your `cards_visa` or `cards_mastercard` balance |
| 404 | `RESOURCE_NOT_FOUND` | Card not found |
| 422 | `VALIDATION_ERROR` | Amount missing or out of range, card not active, or product not reloadable |

<Tip>
  Check your `cards_visa` and `cards_mastercard` balances with `GET /balance` before topping up to avoid `INSUFFICIENT_BALANCE` errors.
</Tip>


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