Browse the docs

Adding a Balance

Let's add a balance to a card!

Money reaches a card in two steps. First you add funds to your Prepaid balance — the balance on your account that is not yet allocated to any card. Then you move part of that balance onto a card. The first is covered in Funding your balance. This page walks through the second on the V1 API; the V2 equivalents are listed at the end.

All requests carry your API key in the x-api-key header.

Add a balance to a card

Now move USD 100 from your prepaid balance onto the card issued in Issuing your first card. amount is a number in major units (dollars, up to two decimals); it must not exceed your available prepaid balance.

Topping up an existing card is free: only the amount you move leaves your prepaid balance. A card-creation fee, where one applies to your account, is charged once when the card is issued — not here. You can also load a card at the moment you issue it, by sending amount on the create request.

cURL

curl --request POST \
     --url https://api.themooncard.com/v1/api-gateway/card/8d2cd518-5ef2-4280-91e8-63b1a0e672e7/add-balance \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'x-api-key: YOUR_API_KEY' \
     --data '{"amount": 100}'

Fetch GET /v1/api-gateway/card/{card_id} when you need the full card details.

JSON

{
  "id": "8d2cd518-5ef2-4280-91e8-63b1a0e672e7",
  "balance": 100,
  "true_balance": 0,
  "expiration": "2029-08-16T00:00:00Z",
  "display_expiration": "08/29",
  "available_balance": 100,
  "terminated": false,
  "card_product_id": "8f1c611d-098d-4f61-b106-f7b6d344b1ae",
  "pan": "4111111111111111",
  "cvv": "",
  "support_token": "9982a86325",
  "frozen": false,
  "activated": false
}

balance and available_balance now show the amount you loaded, and your prepaid balance is USD 100 lower (GET /v1/api-gateway/moon-reserve returns { "balance": 900 }).

Errors you may see:

Status	`code`	When
400	`INSUFFICIENT_BALANCE`	`amount` exceeds your available prepaid balance. `message` states both figures, e.g. `Insufficient balance. Available: 1000, Requested: 5000`.
400	`CARD_PRODUCT_NOT_SUPPORTED`	The card's product is not reloadable.
404	`CARD_NOT_FOUND`	Unknown card id, or a card that belongs to another organization.
404	`USER_BALANCE_NOT_FOUND`	Your organization has no prepaid balance yet — nothing has ever been credited to it. Fund it first: see Funding your balance.

JSON

{
  "message": "Insufficient balance. Available: 1000, Requested: 5000",
  "code": "INSUFFICIENT_BALANCE"
}

Reference: Add balance to card.

The card now holds USD 100 and can be used — try it with Simulating card transactions.

In V2

In V2, funds live in accounts and a card spends from the account it was created with, so you fund the account rather than the card. The equivalent steps are:

GET /v2/api-gateway/moon-reserve — read the organization's prepaid balance.
POST /v2/api-gateway/accounts/transfer — move funds between accounts.

See API versions.

Last updated August 17, 2026