Merchant balance

Top up your USD merchant balance with crypto, and withdraw it back out.

Your merchant balance is a USD float you can spend on payouts and be credited into by collections. These endpoints move crypto in and out of it.

They are not orders in the Flow examples sense — there is no end user. You are funding or draining your own balance.

All routes live under /api/v2/merchant-balance/ and use the standard signed-request headers. See Signing requests.

Availability

These features are gated. Fonbnk must enable them for your account, and creating a deposit or withdrawal also needs a verified merchant organization. Reads, cancels, options and limits stay open once the feature is on.

Error	Code
403	MERCHANT_BALANCE_CRYPTO_DEPOSIT_DISABLED
403	MERCHANT_BALANCE_CRYPTO_WITHDRAW_DISABLED
403	MERCHANT_ORG_NOT_VERIFIED

Deposit lifecycle

1. deposit_awaiting — order created. Send crypto to the address it returns.

2. deposit_validating — you submitted the transaction hash. On-chain confirmation pending.

3. deposit_successful — deposit confirmed.

4. payout_pending — the USD credit is being processed.

5. payout_successful — your balance is credited.

You can cancel a deposit only while it is still deposit_awaiting.

Withdrawal lifecycle

On create, the USD amount is deducted from your balance immediately and the order starts in deposit_successful, waiting for Fonbnk admin approval.

After approval it moves to payout_pending, then payout_successful once the crypto is sent to your address.

If the withdrawal is rejected, or cancelled while still awaiting approval, the order moves to deposit_canceled and the deducted balance is restored.

See Order statuses.

A withdrawal is not instant. It waits on a human. Do not build a flow that assumes same-minute settlement.

Assets

The set here is much narrower than the 44 network/asset pairs the order flows accept. It is USDT and USDC on Celo, Ethereum and BNB, in both directions — six pairs. Everything else, POLYGON included, is rejected up front:

• MERCHANT_BALANCE_DEPOSIT_ASSET_UNSUPPORTED

• MERCHANT_BALANCE_WITHDRAW_ASSET_UNSUPPORTED

The list is two things intersected: which assets our treasury wallets hold for this purpose, and an allowlist we maintain per direction. Both change without a release, so call the relevant .../options endpoint and offer what it returns rather than hard-coding these six.

Limits

Merchant-balance crypto moves are governed by their own rules, separate from order limits, so a busy day of collections cannot exhaust your treasury budget:

Rule	Value
Per transaction, either direction	$5 to $10,000
Withdrawals per calendar month	$10,000 per account

Those are the current defaults for every account. The matching .../limits endpoint is the authoritative answer for a given pair: it starts from these rules and can come back narrower, because the asset's own minimum and precision are applied on top. Read them at runtime with Get limits too — the treasury rules are the ones with criteria.asset: "treasury", and their windowResetsAt tells you when the monthly window rolls over.