Top up a card
Tops up a card from the merchant's available balance. On acceptance the amount plus fee is held (status: pending) and the request goes to the card issuer in the background; it is settled on success and returned to the available balance on failure. The result is sent with the card_funding.status_changed webhook and can be read with GET /card-fundings/{fundingId}.
- Only
activecards can be topped up; rejected when the product'sfeatures.top_upis false. - The amount must be within
limits.top_upfromGET /card-products; otherwise 422. - The fee is
pricing.top_up_fee_rate(percent) plustop_up_fee_fixedfromGET /card-products, rounded down to the currency's precision. order_nomust be unique across the merchant's top-ups and withdrawals.- Some issuers require at least 10 per top-up.
merchantApiKeymerchantTimestampmerchantNoncemerchantSignatureX-API-KEY<token>Merchant API key (starts with upk_, also accepts api-key); signing headers are also required
X-Timestamp<token>Unix timestamp in seconds, within 300 seconds of server time
X-Nonce<token>Unique per request; cannot be reused with the same credential during the timestamp validity window
X-Signature<token>Hex HMAC-SHA256 signature (either letter case) of the method, full path, timestamp, nonce and body digest
cardId*stringapplication/json- body
amount*|Amount in the card currency, greater than 0, with no more decimals than the currency allows
order_no*stringYour order number, unique across the merchant's top-ups and withdrawals
length <= 64Accepted
application/json- response
id*stringTop-up / withdrawal ID (starts with cfd_)
card_id*string|nulltype*stringtop_up or withdraw
"top_up""withdraw"order_no*stringYour order number
amount*stringAmount moved into or out of the card
fee*stringFee; charged on top of a top-up, deducted from the returned amount for a withdrawal
currency*stringstatus*CardFundingStatuspending: accepted, being processed by the issuersucceeded: succeeded and bookedfailed: failed, seefailure_reason; a held top-up amount has been released
"pending""succeeded""failed"failure_reason*string|nullcreated_at*stringdate-timeupdated_at*stringdate-timecurl -X POST 'https://sandbox.getupp.net/api/v1/cards/string/top-up' \ -H 'Content-Type: application/json' \ -d '{ "amount": "100.00", "order_no": "TOPUP-1001"}'{ "id": "cfd_01m5kscprrf7w6nshh1taxd4q9", "card_id": "card_01m5f3kfythx2pw4mpscgnsp4x", "type": "top_up", "order_no": "TOPUP-1001", "amount": "100.00", "fee": "1.50", "currency": "USD", "status": "pending", "failure_reason": null, "created_at": "2026-10-23T07:07:49.000000Z", "updated_at": "2026-10-23T07:07:49.000000Z"}