Merchant balance

Crypto merchant balance

These endpoints let you top up your USD merchant balance with on-chain crypto.

They also let you withdraw your USD merchant balance back out as crypto.

All routes live under /api/v2/merchant-balance/.

All requests use the standard signed-request authentication flow. See Signing requests.

These features are gated.

Fonbnk must enable them for your account.

When a feature is off, the endpoint returns 403 with one of these codes:

Creating a deposit or withdrawal also requires a verified merchant organization.

Otherwise, the endpoint returns 403 MERCHANT_ORG_NOT_VERIFIED.

A crypto deposit moves through these statuses:

deposit_awaiting — order created. Send crypto to depositAddress.
deposit_validating — transaction hash submitted. On-chain confirmation is pending.
deposit_successful — deposit confirmed.
payout_pending — USD credit is being processed.
payout_successful — USD balance is credited.

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

On create, the USD amount is deducted from your balance.

The order starts in deposit_successful and waits for Fonbnk admin approval.

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

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

Call the relevant .../options endpoint to discover supported (network, asset) pairs.

Call the matching .../limits endpoint for the authoritative min and max values.

Unsupported pairs are rejected up front:

Last updated 24 days ago