Settlement Models
Bitnob Payouts supports two core settlement models for customers:
| MODELS | DESCRIPTION |
|---|---|
Wallet-Funded Settlement | Customers pre-fund their Bitnob Wallet and payout transactions are deducted from available wallet balances instantly. |
On-the-Fly Settlement | Customers do not maintain a wallet balance. Each payout is dynamically funded per transaction by paying a generated Bitcoin, Lightning, or USDT address/invoice. |
Both models allow payouts to all supported countries and channels.
1. Wallet-Funded Settlement (Traditional Model)
In this model:
Customer pre-funds their Bitnob Business Wallet using Bitcoin, USDT, or supported local currencies.
Payout API calls deduct directly from the available wallet balance.
Payouts are processed instantly after basic validation (KYC/KYB, liquidity, compliance).
Wallet balance is updated immediately upon payout initiation.
Best suited for high-volume companies or treasury teams comfortable managing float internally.
Wallet-Funded Payout Flow
sequenceDiagram
participant Customer
participant Bitnob Wallet
participant Payout Engine
participant Bank/Mobile Money
Customer->>Bitnob Wallet: Fund wallet
Customer->>Payout Engine: POST /v1/payouts
Payout Engine->>Bitnob Wallet: Deduct payout amount
Payout Engine->>Bank/Mobile Money: Send payout
Bank/Mobile Money-->>Payout Engine: Payout complete
Payout Engine-->>Customer: Webhook payout.success or payout.failed
2. On-the-Fly Settlement (Dynamic Payment Model)
In this model:
Customer requests a quote for a specific payout (POST /api/payouts/quotes).
Bitnob returns the quote details:
Required amount to fund,
Expiry timestamp (typically 15 minutes),
Quote ID.
Customer initiates payout by referencing the quoteId and providing beneficiary details (POST /api/payouts/initiate).
Bitnob returns a payment address or invoice (Bitcoin/Lightning/USDT, depending on source selected).
Customer pays the address or invoice within the expiry window.
Bitnob confirms receipt of the payment.
Bitnob executes the fiat payout to the beneficiary immediately after confirmation.
Customer receives webhook updates during each critical phase.
Best suited for companies who want flexible treasury management without maintaining idle wallet balances.
On-the-Fly Payout Flow (Bitnob Real Flow)
sequenceDiagram
participant Customer
participant Bitnob Quote Service
participant Bitnob Payment Engine
participant Blockchain/Lightning
participant Payout Engine
participant Bank/Mobile Money
Customer->>Bitnob Quote Service: POST /payouts/quotes
Bitnob Quote Service-->>Customer: Returns quoteId + payment details
Customer->>Bitnob Payment Engine: POST /payouts/initiate with quoteId
Bitnob Payment Engine-->>Customer: Returns funding address/invoice
Customer->>Blockchain/Lightning: Pays invoice/address
Blockchain/Lightning-->>Bitnob Payment Engine: Payment confirmed
Bitnob Payment Engine->>Payout Engine: Initiate fiat payout
Payout Engine->>Bank/Mobile Money: Send payout
Bank/Mobile Money-->>Payout Engine: Payout confirmation
Payout Engine-->>Customer: Webhook payout.success or payout.failed
Important Concepts in On-the-Fly Model
| CONCEPT | EXPLANATION |
|---|---|
Quote Expiry | Quotes expire after a fixed time (e.g., 15 minutes). After expiry, new quotes must be requested. |
Partial Payments | Underpayments result in adjusted payouts; overpayments are credited back to the customer’s internal balance. |
Payment Sources | Supports Bitcoin (BTC), USDT (various chains), Lightning Network payments. |
Timeout Handling | If payment is not received within the expiry window, the payout request is invalidated. |
Webhook Triggers | Customers are notified via webhook events for asset receipt, payout processing, and payout completion. |
Supported Funding Sources for On-the-Fly Settlement
| FUNDING SOURCE | AVAILABLE NOTES |
|---|---|
Bitcoin (BTC) | Pay exact BTC amount required for payout. |
USDT (Tether - TRC20, ERC20, or other chains) | Pay exact USDT required. |
Lightning Network | Pay fast and low-cost using a Lightning invoice. |
Webhooks Timeline for On-the-Fly Payouts
| EVENT | MEANING |
|---|---|
payouts.asset.received | Payment to funding address confirmed. |
payouts.withdrawal.processing | Fiat payout has been initiated. |
payouts.withdrawal.success | Recipient successfully received payout. |
payouts.withdrawal.failed | Payout failed after payment due to delivery issues (rare). |
payouts.withdrawal.expired | Payout expired because no payment was received within quote window. |
Choosing a Settlement Model
| MODEL | BEST FOR | PROS | CONS |
|---|---|---|---|
Bitcoin (BTC) | High-volume companies managing float internally | Instant payout execution, lower friction per transaction | Requires treasury top-ups and internal liquidity management |
On-the-Fly | New businesses, lightweight startups, flexible treasury operations | No wallet top-ups needed, simple reconciliation | Requires per-transaction funding discipline, quote expiries |
Summary
Wallet-Funded Settlement is designed for speed and volume. On-the-Fly Settlement is designed for flexibility and cash efficiency.
Both models can coexist depending on your operational needs.
With Bitnob, you can scale payouts globally — either with a funded operational wallet, or per transaction, per payment.
Move Bitcoin and stablecoins across borders
Deliver payouts without infrastructure headaches.
