How to Send Payouts with Bitnob

If you're building applications that need to send money across borders especially within Africa. Bitnob's payout APIs let you convert crypto (BTC, USDT, USDC) into local fiat currencies (NGN, GHS, KES, etc.) without managing your own liquidity or settlement rails.

This guide focuses on one thing only:

How to successfully execute a payout from start to finish

Authentication required

Every request must be signed with HMAC-SHA256. See the Authentication reference for the full signing flow.

The Payout Flow

To send money using Bitnob, you only need to follow three steps:

Create Quote → Initialize → Finalize

Quote → defines the settlement amount and conversion

Initialize → attaches recipient details and prepares the payout for execution

Finalize → executes the payout

1. Create a Payout Quote

Before anything else, you must create a quote. This defines:

How much crypto are you sending

How much fiat the recipient will receive

the exchange rate and fees

You can alternatively provide settlement_amount if you want to target a specific fiat value instead of a crypto amount.

Endpoint

Create Quote

Example Request

json

You can decide to make a source of crypto from an external wallet, which requires an on-chain transaction to the generated address provided by Bitnob

Example Request (on-chain)

json

Response

json

What to pay attention to

quote_id → used to initialize and finalize the payout

settlement_amount → what the recipient gets

expires_at → quotes are time-bound

If the quote expires, you must create a new one.

2. Initialize the Payout

This step attaches the beneficiary (recipient) and prepares the payout.

Endpoint

Initialize Payout

Example Request

json

Response Field

json

What happens here

The payout moves from QUOTE → INITIATED

Recipient details are validated

The transaction is prepared — but not executed yet

3. Finalize the Payout

This is the step that actually sends the money.

Endpoint

Finalize Payout

What happens here

Your wallet is debited

The payout is submitted to the settlement rail

Status moves to PENDING (or next processing state)

Example Response

json

SWIFT Payouts (Cross-Border Wires)

When a destination country or currency does not support local payout rails, Bitnob uses SWIFT. This is the fallback rail for international bank transfers (USD, EUR, GBP, HKD, etc.)

The key difference

The flow remains:

Create Quote → Initialize → Finalize

But:

SWIFT requires full beneficiary (wire) details during the initialize step

1. Create a SWIFT Quote

Endpoint

Create SWIFT Quote

Example Request

json

Example Response

json

2. Initialize the Payout (SWIFT Details)

This is where SWIFT differs from local payouts.

You must provide full wire instructions here.

Endpoint

Initialize SWIFT Payout

Example Request

json

Response

json

3. Finalize the Payout

Same final step as every payout.

Endpoint

Finalize SWIFT Payout

No request body required.

Same Model, Different Rail

Even with SWIFT, nothing changes conceptually:

Quote = price lock

Initialize = attach recipient

Finalize = send money

Payout Webhooks

Payout webhooks are fired when there is a transfer of funds.

transfer successful

json

transfer failed

json