Payouts Lifecycle
Understanding the full lifecycle of a payout is critical for designing reliable systems and anticipating every possible event during the transaction journey.
At Bitnob, a payout typically passes through five major stages:
| STAGE | DESCRIPTION |
|---|---|
1 | Quote Requested |
2 | Payout Initiated |
3 | Funding Detected |
4 | Fiat Payout Processing |
5 | Completion (Success, Failure, or Expiry) |
Each stage updates the payout’s Trip timeline, and key webhook events are triggered to notify you of important transitions.
Lifecycle Diagram
flowchart TD
A[Quote Requested] --> B[Payout Initiated]
B --> C[Payment Made to Funding Address]
C --> D[Funding Confirmed]
D --> E[Fiat Payout Processing Started]
E --> F{Completion}
F -->|Success| G[Payout Delivered Successfully]
F -->|Failure| H[Payout Failed]
F -->|Expired| I[Payment Window Expired, Payout Canceled]
Step-by-Step Breakdown
1. Quote Requested
Action:
Customer calls POST /api/payouts/quotes.
Bitnob returns a quoteId with the amount to pay, destination currency, FX rate, and expiry timestamp.
Important:
Quote has a strict expiry time (typically 15 minutes).
Customer must initiate payout before the quote expires.
2. Payout Initiated
Action:
Customer calls POST /api/payouts/initiate with the quoteId and beneficiary details.
Bitnob responds with:
A payment address (BTC/USDT address or Lightning invoice),
Funding amount,
Trip ID to track the lifecycle.
Webhook:
No webhook yet. Customer is expected to pay.
3. Funding Detected
Action:
Customer pays the provided address/invoice.
Bitnob detects incoming payment (assetReceivedAt) .
Webhook Event:
| EVENT | MEANING |
|---|---|
payouts.asset.received | Asset detected on-chain or over Lightning. |
4. Fiat Payout Processing
Action:
After payment is fully confirmed (assetConfirmedAt), Bitnob initiates fiat payout to beneficiary (bank, mobile wallet, cash pickup).
Webhook Event:
| EVENT | MEANING |
|---|---|
payouts.withdrawal.processing | Fiat payout is now underway. |
5. Completion (Success, Failure, or Expiry)
| OUTCOME | DESCRIPTION | WEBHOOK |
|---|---|---|
Success | Fiat funds delivered to the beneficiary account. | payouts.withdrawal.success |
Failure | Fiat payout failed (e.g., invalid account, system downtime). | payouts.withdrawal.failed |
Expired | Payment not received within quote window; payout canceled. | payouts.withdrawal.expired |
Final Trip Timeline Snapshot:
completionTime is recorded,
timeToFinish is recorded, is calculated,
Webhooks delivered to customer systems.
Quick Summary Table
| Lifecycle Stage | Trigger | Trip Fields | Webhooks |
|---|---|---|---|
Quote Requested | POST /payouts/quotes | quoteAt | - |
Payout Initiated | POST /payouts/initiate | submittedAt, initializedAt | - |
Funding Detected | Payment observed on-chain | assetReceivedAt | payouts.asset.received |
Funding Confirmed | Full confirmation thresholds met | assetConfirmedAt | - |
Payout Processing | Fiat payout dispatched | processingAt | payouts.withdrawal.processing |
Payout Completion | Success, failure, or expiry | settlementAt or settlementFailedAt, completionTime | payouts.withdrawal.success, payouts.withdrawal.failed, payouts.withdrawal.expired |
Developer Best Practices
Treat every payout as a lifecycle with stages, not a single API call.
Use Trip ID as the anchor to track a payout through all webhook updates and fetches.
Handle both funding events and payout events separately — they are not the same.
Build for timeouts and failures gracefully (expired quotes, rejected payouts).
Log and monitor key lifecycle timestamps to improve operational efficiency and incident detection.
Random Thought
In Bitcoin + fiat hybrid payments, payout success depends not just on payment, but on orchestrating funding, confirmation, fiat liquidity, compliance, and beneficiary delivery together.
This lifecycle documentation gives you the full map to operate confidently.
