Card Funding
What Is 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
✅ You don’t need to hold USD directly.
✅ Bitnob handles the exchange and top-up logic atomically.
When Can You Fund a Card?
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).
Funding Constraints
| 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) |
API Endpoint
Request Body
Parameters
| Field | Type | Required | Description |
|---|---|---|---|
| cardId | String | ✅ | Unique ID of the card you want to fund |
| amount | Number | ✅ | USD amount to fund (e.g. 50 = $50) |
| sourceAsset | String | ✅ | Asset you're funding with (e.g. USDT_TRC20, BTC, NGN) |
Example Response
✅ USD value is added to the card’s available spend balance instantly.
Webhook: card.funded
Whenever a card is successfully funded, Bitnob sends:
Error Scenarios
| 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) |
Best Practices
| 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 |
Funding Strategy Patterns
| 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. |
FAQ
Can I top up a card multiple times?
Can users fund their own cards directly?
What if the FX rate changes during funding?
Can I get funding failure webhooks?
