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

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/initialize 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.

Note

If payment is too late (after expiry), payout may be canceled or manually reconciled.

If underpaid, payout will adjust down proportionally.

4. Fiat Payout Processing

Action:

After payment is fully confirmed (assetConfirmedAt), Bitnob initiates fiat payout to beneficiary (bank, mobile wallet, cash pickup).

Webhook:

event	meaning
payouts.withdrawal.processing	Fiat payout is now underway.

Note

Payout processing depends on the destination country/rail speed (NIP, SEPA, ACH, Mobile Money, etc.)

If the beneficiary account details are invalid, payout may fail here.

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/initialize	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.