Card Funding

Card funding is the process of loading USD value onto a virtual Visa card created through Bitnob.

Since the cards are prepaid , they must be funded before the cardholder can spend.

Bitnob allows you to fund cards using your available balance , which can be made up of:

Stablecoins (e.g.USDT TRC20, ERC20, or USDC)

Bitcoin (BTC)

We handle FX conversion behind the scenes to settle USD to the card.

Funding Architecture

Funding Architecture Flow

You don’t need to hold USD directly.

Bitnob handles the exchange and top-up logic atomically.

You can fund a card:

Immediately after creation (as part of onboarding),

Just before a transaction (e.g. one-time funding flow),

Periodically (e.g. daily limits),

On demand (user-triggered top-up from app/dashboard).

constraint	description
Maximum Card Balance	Defined per partner account (e.g. $10,000/card)
Min Funding	Minimum top-up per request (e.g. $1)
FX Tolerance	Funding will fail if source asset value changes too much between quote and execution
Available Wallet Balance	You cannot fund more than what you hold in your Bitnob wallet
Settlement Delay	Funds are added immediately once Bitnob confirms internal swap/liquidity (usually sub-second)

JSON Request Body

field	type	required	description
cardId	String	Yes	Unique ID of the card you want to fund
amount	Number	Yes	USD amount to fund (e.g. 50 = $50)
sourceAsset	String	Yes	Asset you're funding with (e.g. USDT_TRC20, BTC, NGN)

JSON Response

USD value is added to the card’s available spend balance instantly.

Whenever a card is successfully funded, Bitnob sends:

Webhook Payload

scenario	http code	solution
Insufficient Wallet Balance	400	Top up your Bitnob wallet before funding
Card is Frozen or Terminated	403	Cannot fund non-active card
Source Asset Unsupported	400	Only specific stablecoins, fiat, or BTC allowed
Exchange Rate Expired	409	Retry funding (rate too old or volatility too high)

tip	why it helps
Always confirm card status is "active" before funding	Prevents rejections
Log exchange rate used	Helps with reconciliation and FX audit
Track webhook confirmation	Don't assume success from HTTP 200 alone
Allow user-triggered top-up flows	Makes cards more usable in consumer apps
Use wallet balance viewer (GET /wallets/:id) before funding	Prevents avoidable failures

pattern	description
On-demand	App triggers top-up when user clicks “Top Up Card”
Auto-fund	Fund card automatically when user's balance hits threshold
Per-event	Load card right before transaction (e.g. payroll payout → card fund)
Recurring	Schedule top-ups for monthly allowances, spend programs, etc.

Q:Can I top up a card multiple times?

Yes. You can fund a card repeatedly until it reaches the maximum allowed balance.

Q:Can users fund their own cards directly?

Currently all funding is initiated by the platform via API. User wallets must be managed by you.

Q:What if the FX rate changes during funding?

Bitnob applies the latest available rate and rejects funding if the deviation is too high.

Q:Can I get funding failure webhooks?

Funding failures return HTTP errors and are logged in your webhook error dashboard.