Requesting a Quote and Initiating a Payout

In the On-the-Fly Settlement model, payouts are powered by dynamic funding based on real-time quotes.

Before initiating any payout, you must first request a quote for the specific transaction you intend to fund.

Step 1: Request a Payout Quote

Full request and response reference: Create Payouts Quote.

Endpoint

field	type	required	description
from_asset	String	Yes	The crypto asset to convert from (e.g., BTC, USDT, USDC).
to_currency	String	Yes	The destination fiat currency for the payout (e.g., NGN, KES).
source	String	Yes	The source of funds: 'onchain' for blockchain deposit or 'offchain' for wallet balance.
amount	String	Yes*	The crypto amount to convert. Required if settlement_amount is not provided.
settlement_amount	String	Yes*	The target fiat amount to receive. Required if amount is not provided.
chain	String	No	The blockchain network (e.g., BITCOIN, trc20, erc20). Required when source is 'onchain'.
payment_reason	String	Yes	Description of the payment purpose.
reference	String	Yes	Your unique reference for this quote.
country	String	Yes	Two-letter ISO country code for the destination (e.g., NG, KE).

Example Request

field	description
id	Unique identifier for the generated payout quote.
status	Current state of the quote (e.g., 'QUOTE').
quote_id	Reference used to identify the payout quote.
settlement_amount	Amount to be settled in the settlement currency.
exchange_rate	Object holding the FX conversion applied — rate, btc_rate, currency and effective_rate.
amount	Original crypto amount provided when creating the quote.
from_asset	The crypto asset used for the payout (e.g., USDT, BTC).
to_currency	The destination fiat currency (e.g., NGN, KES).
expires_at	ISO 8601 timestamp indicating when the quote expires.
fees / cent_fees	Fees applied to the payout, in major units and in minor units respectively.

Step 2: Initialize the Payout Using the Quote

Full request and response reference: Initialize Payout.

Endpoint

Request Body Parameters

field	type	required	description
customer_id	String	Yes	Unique identifier for the customer initiating the transaction.
beneficiary	Object	Yes	Bank or wallet details of the recipient. Structure varies by country — use GET /api/payouts/supported-countries/:countryCode/requirements.
reference	String	Yes	Unique reference for this payout transaction.
payment_reason	String	No	Reason or narration for the payout.
callback_url	String	No	Webhook URL to receive payout status updates for this transaction.
client_meta_data	String	No	JSON string of custom metadata for internal tracking.

The beneficiary structure varies by destination — fetch the corridor requirements with Get Country Details, the bank list with Get Banks, and confirm the account resolves with Account Lookup.

Example Request

Create Payout - Request

Example Response

Initialize Payouts - Response

Step 3: Pay the Address / Invoice

Customer must send the exact amountToPay to the paymentAddress.

Payment must happen before the expiresAt timestamp.

After payment is detected, Bitnob automatically proceeds with the fiat payout.

Step 4: Monitor Webhooks or Fetch Status

Bitnob triggers webhook notifications or allows status checking via Get Payout by ID:

Endpoint

status	meaning
awaiting_payment	Waiting for customer to fund the payout.
payment_received	Payment confirmed — payout processing begins.
processing	Fiat payout underway.
success	Payout completed to beneficiary.
failed	Payout failed due to delivery issue.
expired	Quote expired without payment.

Summary

Request a quote → Initiate payout → Pay → Receive updates.

Flexible funding with Bitcoin, USDT, or Lightning.

Fully event-driven, real-time settlement into bank accounts or mobile wallets.

Built for speed, simplicity, and scalability.

This now properly matches your internal Offramps flow:

Endpoint

Payment address,

Webhooks + Status tracking.