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
Response
The call returns 202: the top-up is accepted and applied asynchronously.
How it works
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.- The card is credited with
amount.
- You receive a
card.topup.completed webhook once the card is credited.
- 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
Check your cards_visa and cards_mastercard balances with GET /balance before topping up to avoid INSUFFICIENT_BALANCE errors.
