Skip to main content
POST
Top up a reloadable card from the account balance

Authorizations

Authorization
string
header
required

Firebase ID token from /auth or any paid route, sent as a Bearer token: Authorization: Bearer <id_token> (the Bearer prefix is required).

Headers

Idempotency-Key
string

Optional client-generated unique key (a UUID works) that makes this write safe to retry. A retry with the same key within 24 hours returns the recorded response of the original request, marked with an Idempotency-Replayed: true header, instead of performing the write again. Reusing a key with a different body or route is rejected with 422 (code: idempotency_key_reused); a retry that arrives while the original is still running gets 409 (code: idempotency_key_in_progress), so wait a moment and retry with the same key. Keys are scoped to the authenticated account.

Maximum string length: 255

Body

application/json
amount
number
required

USD to move from the account balance onto the card balance (min $5, max $10,000).

Required range: 5 <= x <= 10000

Response

The account balance was debited and the top-up is on its way to the card balance.

top_up_id
string

Identifies this top-up under top_ups in GET /list-card-transactions.

status
string

Always paid: the account balance has been debited. Follow the top-up through bridging, delivered, and credited in GET /list-card-transactions.

Example:

"paid"

funded_usd
number

USD debited from the account balance and loaded onto the card balance.

note
string

What happens next and how to track it.