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

Endpoint

field	type	required	description
fromAsset	String	Instant payout execution, lower friction per transaction	The asset you intend to fund the payout with. (e.g., BTC, USDT)
toCurrency	String	Yes	The destination fiat currency for the payout. (e.g., NGN, GHS, KES)
source	String	Yes	The payout source type. (e.g., BankAccount, MobileMoney, CashPickup)
amount	String	Yes	Amount to be delivered to the recipient,
chain	String	No	(Optional) For USDT, specify the blockchain (e.g., TRC20, ERC20) if needed.

json

Create Payouts Quote - Response

field	description
id	Unique identifier for the generated payout quote.
status	Current state of the quote (e.g., `quote`).
settlementCurrency	Currency in which the payout will be settled.
quoteId	Human-readable reference used to identify the payout quote.
settlementAmount	Amount to be settled in the settlement currency.
btcRate	Bitcoin rate used to calculate the payout.
exchangeRate	FX conversion rate applied for the settlement.
expiryTimeStamp	Unix timestamp indicating when the quote expires.
amount	Original amount provided when creating the quote.
satAmount	Equivalent Bitcoin amount in satoshis.
expiresInText	Human-readable text showing how long the quote remains valid.
quoteText	Formatted message summarizing the settlement amount.

Endpoint

field	type	required	description
quoteId	String	Yes	The quote identifier returned when creating the payout quote.
customerId	String	No	Optional customer identifier for internal tracking.
country	String	Yes	ISO country code of the payout destination (e.g., `NG`).
reference	String	Yes	Unique reference for this payout transaction.
beneficiary	Object	Yes	Beneficiary payout details including type, bank code, and account number.
paymentReason	String	No	Reason or narration for the payout.
callbackUrl	String	No	Webhook URL to receive payout status updates for this transaction.
clientMetaData	Object	No	Additional metadata you want to attach to the payout request.

Create Payout - Request

Initialize Payouts - Response

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.

Bitnob triggers webhook notifications or allows status checking via:

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.

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

Flexible funding with Bitcoin, USDT, or Lightning.

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

Built for speed, simplicity, and scalability.

This now properly matches your internal Offramps flow:

Endpoint

Payment address,

Webhooks + Status tracking.