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
| 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. |
Example Request
Example Response
| FIELD | DESCRIPTION |
|---|---|
quoteId | Unique ID used to lock this payout rate temporarily. |
fundingAmount | StriAmount the customer must pay in the fundingAsset.ng |
rate | FX conversion rate applied. |
expiresAt | Time at which this quote becomes invalid (typically 15 minutes). |
Step 2:Initiate the Payout Using the Quote
Request Body Parameters
| FIELD | TYPE | REQUIRED | DESCRIPTION |
|---|---|---|---|
quoteId | String | Yes | The quoteId you received from the previous step. |
beneficiary | Object | Yes | Full beneficiary details (name, account number, bank name, etc.) |
customerId | String | No | (Optional) Unique identifier for tracking at your system level. |
callbackUrl | String | No | (Optional) Webhook URL to receive payout updates specifically for this transaction. |
Example Request
Example Response
| FIELD | DESCRIPTION |
|---|---|
reference | Unique identifier for the payout request. |
paymentAddress | Address to pay (could be a BTC address, a USDT address, or a Lightning Invoice). |
amountToPay | Amount the customer must send to Bitnob to fund this payout. |
expiresAt | When the funding address expires if unpaid. |
status | Current payout status (awaiting_payment, processing, etc.) |
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:
| 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, mobile wallets, or cash pickup channels.
Built for speed, simplicity, and scalability.
This now properly matches your internal Offramps flow:
Payment address,
Webhooks + Status tracking.
