'/%3e%3cdefs%3e%3cpattern%20id='pattern0_2104_4598'%20patternContentUnits='objectBoundingBox'%20width='1'%20height='1'%3e%3cuse%20xlink:href='%23image0_2104_4598'%20transform='matrix(0.00376176%200%200%200.0172414%20-0.00219436%200)'/%3e%3c/pattern%3e%3cimage%20id='image0_2104_4598'%20width='267'%20height='58'%20preserveAspectRatio='none'%20xlink:href='data:image/png;base64,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'/%3e%3c/defs%3e%3c/svg%3e)
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. Four webhook events are emitted: payouts.initialized when the payout is accepted for processing, payouts.processing when the settlement rail picks it up, and payouts.withdrawal.success or payouts.withdrawal.expired on the terminal outcome. Intermediate stages are observed by polling GET /api/payouts/:id.
Lifecycle Diagram
Step-by-Step Breakdown
1. Quote Requested
Action:
Customer calls POST /api/payouts/quotes.
Bitnob returns a quote_id 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/:quoteId/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:
payouts.initialized is emitted once the payout is accepted for processing. Nothing has settled yet — the customer is still expected to pay.
3. Funding Detected
Action:
Customer pays the provided address/invoice.
Bitnob detects the incoming payment.
Status — observe by polling GET /api/payouts/:id (no webhook is sent at this stage):
event | meaning |
|---|---|
Asset received (status) | Asset detected on-chain or over Lightning. |
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, Bitnob initiates the fiat payout to the beneficiary (bank, mobile wallet, cash pickup).
Webhook: payouts.processing is emitted when the rail picks up the payout.
event | meaning |
|---|---|
Processing (status) | Fiat payout is now underway. |
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). The payout record moves to status FAILED. | — (poll GET /api/payouts/:id ) |
Expired | Payment not received within the quote window; payout canceled. | payouts.withdrawal.expired |
Final Trip Timeline Snapshot:
completion_time is recorded on the terminal state,
Webhooks delivered to customer systems.
Quick Summary Table
lifecycle stage | trigger | trip fields | webhooks |
|---|---|---|---|
Quote Requested | POST /api/payouts/quotes | quote_at | - |
Payout Initiated | POST /api/payouts/:quoteId/initialize | initialized_at | payouts.initialized |
Funding Detected | Payment observed on-chain | - | - |
Funding Confirmed | Full confirmation thresholds met | finalized_at | - |
Payout Processing | Fiat payout dispatched | processing_start | payouts.processing |
Payout Completion | Success, failure, or expiry | completion_time | payouts.withdrawal.success, 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.