> ## Documentation Index > Fetch the complete documentation index at: https://www.bitnob.dev/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > Bitnob API requests authenticate with an `X-Auth-Client` API key header against https://api.bitnob.com. > Always use the sandbox environment for testing. Never put live API keys in sample code. > Money amounts are integers in the smallest unit of the currency (satoshis for BTC, cents for fiat). Never use floats. > Every state-changing request takes a client-supplied `reference` and must be treated as idempotent on retry. > Quotes expire. Re-quote rather than reusing a stale quote id. # Module 4: The payout lifecycle, stage by stage > The five stages a payout moves through, what can fail at each one, and what your team must watch. A payout is not one event. It is a record that moves through five stages, and it can stop at any of them. You cannot monitor a process you cannot describe, so this module describes it. ## What you will learn * The five stages, and what changes at each one * What fails at each stage, and how you detect it * Which timestamps let you answer "where is my money" ## The five stages | Stage | Status | What is happening | | - | - | - | | 1 | `QUOTE` | A rate and a fee are locked for a short window. | | 2 | `INITIATED` | The beneficiary is attached. Funding is expected. | | 3 | `PENDING_ADDRESS_DEPOSIT` | Waiting for the user to pay the funding address. | | 4 | `PROCESSING` | The local rail is delivering the money. | | 5 | `SUCCESS` or `FAILED` | The payout finished, one way or the other. | Each transition writes a timestamp to the payout's `trip` object, and some transitions send a webhook. Full detail is in [Statuses and webhook events](https://www.bitnob.dev/docs/payouts/statuses-and-webhook-events.md). ## Stage 1: The quote You request a quote with the source asset, the destination currency, and the amount to deliver. You receive a funding amount, a locked rate, an expiry time, and a quote id. **What fails here.** The user takes too long and the quote expires. If you hold quotes open, you carry the price movement yourself. **What to do.** Show the expiry as a countdown, not a timestamp. Fetch a new quote rather than reusing an old one. ## Stage 2: Initialization The user accepts the quote and supplies the beneficiary: a bank account or a mobile money wallet. You receive a funding address or a Lightning invoice. **What fails here.** The beneficiary details are wrong, or the user pays on a different chain from the address you issued. **What to do.** Validate the account before you initialize, using [Account lookup](https://www.bitnob.dev/api-reference/payouts/account-lookup.md). Show the chain beside the address, and never display an address without it. ## Stage 3: Funding The user pays. The network reports the transaction, then confirms it. Delivery only starts after confirmation. The Trip records `asset_received` when the funding arrives. Until then, the payout stays waiting for the deposit. **What fails here.** * The user sends less than the funding amount. * The user sends more than the funding amount. * Network congestion delays confirmation. * The payment arrives after the quote expired. **What to do.** Alert when funding stays unconfirmed longer than the corridor's normal time. A shortfall beyond a very small tolerance is refused, so decide how you’ll handle the user’s funds if that happens. Decide where an overpayment goes. ## Stage 4: Delivery The local rail moves the money to the beneficiary. Each rail has its own speed. | Rail | Typical delivery | | - | - | | Nigeria NIP | Minutes | | UK Faster Payments | Minutes | | SEPA | Hours, sometimes the next working day | | Mobile money | Seconds to minutes | **What fails here.** The bank rejects the account. The mobile money operator is down. The rail runs out of local liquidity. **What to do.** Measure delivery time per corridor, not as one average. Tell the user when delivery starts. Retry only failures that are safe to retry. ## Stage 5: Completion The payout reaches `SUCCESS` or `FAILED`, or expires without funding and moves to `EXPIRED`. Five events report this: `payouts.initialized`, `payouts.processing`, `payouts.withdrawal.success`, `payouts.withdrawal.expired`, and `payouts.withdrawal.failed`. > [!WARNING] > > Webhooks can be missed. If your system only reacts to webhooks, a failed payout can stay "processing" in your records forever. Reconcile against [Get payout](https://www.bitnob.dev/api-reference/payouts/get-payout.md) on a schedule. **What to do.** Confirm success to the user explicitly. Contact the user yourself when a payout fails, before they contact you. Track how long each corridor takes from quote to completion. ## The full flow ![Payout flow](https://mintcdn.com/bitnob/5PGS9OuNC096evyI/images/payou-flow.svg?fit=max\&auto=format\&n=5PGS9OuNC096evyI\&q=85\&s=0444925de920ac6ae3cd6339b4d03cc1) ## Exercise: design the operations view Your operations team needs one screen. Build it to answer three questions: 1. Which payouts are waiting for funding confirmation, and for how long? 2. Which payouts have been `PROCESSING` for longer than 15 minutes? 3. Which corridors have a rejection rate above 2% today? A team that can answer those three questions finds problems before users report them. A team that cannot is waiting for complaints. ## Checklist for product managers * Map every payout in your product to these five stages. * Define an alert for each transition that can stall. * Store the payout id and your reference so you can rebuild any payout's history. * Match your user messages to the real stages, not to your API calls. * Set a target delivery time per corridor, and measure against it. ## Summary A payout product is judged on what happens between the request and the arrival. Learn the five stages, watch each transition, and the failures become visible while you can still fix them. > [card] [Next: Error handling](https://www.bitnob.dev/learn/courses/payouts-for-product-managers/module-5.md) > > What to do when a payout fails, at each stage. > [card] [See it in the API](https://www.bitnob.dev/docs/payouts/payouts-lifecycle.md) > > The lifecycle as the API reports it. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.