Browse the docs

Move card balance to the prepaid balance

POST /v1/api-gateway/card/{card_id}/move-balance

Moves amount from a reloadable Moon Prepaid card back to your organization's prepaid balance. Only available to organizations with balance movement enabled — contact Moon support to enable it.

Request

Authentication: your API key in the x-api-key header.

Path parameters

Field	Type	Description
`card_id` required	string, uuid	Card UUID (the card `id` returned by the card endpoints).

Headers

Field	Type	Description
`Idempotency-Key`	string	A unique string you choose, up to 255 characters, that makes this request safe to retry. If a request times out or fails in transit, send it again with the same key: the status code and body of the first attempt are returned and the operation is not performed a second time. Stored replies — including failures — are replayed for 24 hours, after which the same key starts a fresh request. Reusing a key for a different request, or sending it while the first request is still running, returns 409. Omit the header and the request behaves exactly as before. Document upload endpoints do not accept it.

Body

Field	Type	Description
`amount` required	number	Amount to move from the card back to your organization's prepaid balance, in major units (e.g. `25.50`). Must be at least `0` and not exceed the card balance; `0` moves nothing.

Example request

cURL

curl --request POST \
     --url 'https://api.themooncard.com/v1/api-gateway/card/7c9e6679-7425-40de-944b-e07fc1f90ae7/move-balance' \
     --header 'x-api-key: YOUR_API_KEY' \
     --header 'content-type: application/json' \
     --data '{
       "amount": 25.5
     }'

Responses

200 Success

{ "message": "Balance moved to Moon Credit" }.

Field	Type	Description
`message` required	string	Human-readable confirmation of what happened. The wording is fixed per route — the response description on each operation quotes it — but it is not a stable machine key: branch on the 2xx status, not on this text.

JSON

{
  "message": "Balance moved to Moon Credit"
}

400 Error

Validation failed, the card is not a reloadable Moon Prepaid card (CARD_NOT_RELOADABLE), or the card does not hold amount (INSUFFICIENT_BALANCE).