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 automatically.

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 Funding	Maximum Card Funding: $50,000 per card
Maximum Funding Per Transaction	Maximum Funding Per Transaction: $2,500
Minimum Funding	Minimum top-up per request (e.g. $2)
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)

For full request and response details, see the Fund Card API Reference.

API Endpoint

JSON Request Body

field	type	required	description
card_id	String (UUID)	Yes	The unique identifier of the card to fund.
amount	Integer	Yes	The amount to add to the card balance in microunits (e.g., 2000000 = $20.00 USD, where 1 USD = 100000 microunits).
reference	String	Yes	A unique reference identifier for this funding transaction. Used for idempotency and reconciliation.
description	String	No	A human-readable description for this funding transaction (e.g., "Monthly expense allowance").

JSON Response

Whenever a card is successfully funded, Bitnob sends a webhook. For full webhook details, see the Card Issuing Webhooks page.

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 up to $2,500 per transaction, and continue funding until the card reaches a maximum balance of $50,000.

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.