> ## 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.

# Payout statuses and webhook events

> The payout record status vocabulary and the webhook event vocabulary are different. This page lists both, side by side, with the mapping between them.

Payouts expose two vocabularies that are easy to conflate:

* The **record status**: uppercase, returned by [Get payout](https://www.bitnob.dev/api-reference/payouts/get-payout.md) as `status`.
* The **webhook event**: dotted lowercase names, delivered to your callback URL, whose `data.status` field carries a lowercase event outcome.

Check the `event` field to decide how to handle a webhook, never `data.status`.

## Record statuses

| Status | Meaning |
| - | - |
| `QUOTE` | Quote created, not yet initialized. |
| `INITIATED` | Initialized against the quote with a beneficiary, offchain funding. Nothing debited yet. |
| `PENDING_ADDRESS_DEPOSIT` | Initialized, onchain funding. Waiting for you to pay the returned `address`. |
| `PENDING` | Finalized and queued for dispatch. |
| `PROCESSING` | Funded. The fiat leg is underway on the local rail. |
| `SUCCESS` | Funds delivered to the beneficiary. The only success state. |
| `FAILED` | The fiat leg could not be completed. |
| `EXPIRED` | The quote expired before funding arrived. Nothing settled. |

## Webhook events

| Event | Fires when | Terminal |
| - | - | - |
| `payouts.initialized` | The payout is initialized against a quote and accepted for processing. | No |
| `payouts.processing` | Bitnob starts sending the payout to the settlement rail. | No |
| `payouts.withdrawal.success` | Funds are delivered to the beneficiary. | Yes |
| `payouts.withdrawal.expired` | The quote expired before funding arrived. Nothing settled. | Yes |
| `payouts.withdrawal.failed` | The payout failed. `failure_reason` says why. | Yes |

These five are the complete catalog. Back them up with polling [Get payout](https://www.bitnob.dev/api-reference/payouts/get-payout.md), because webhooks can be missed. Payload shapes for each event are on [Receive payout webhooks](https://www.bitnob.dev/docs/payouts/webhook-payout.md).

## `data.status` inside a webhook

The `data.status` field inside a webhook payload is the lowercase event outcome, one of `initiated`, `pending_address_deposit` (onchain funding), `processing`, `success`, `expired`, or `failed`. It is not the record status vocabulary above, even where the words look similar.

## How the two line up

| Record status | Event you may receive at that point |
| - | - |
| `QUOTE` | none, and `payouts.withdrawal.expired` if it expires |
| `INITIATED`, `PENDING_ADDRESS_DEPOSIT` | `payouts.initialized`, and `payouts.withdrawal.expired` if never funded |
| `PENDING` | none |
| `PROCESSING` | `payouts.processing` |
| `SUCCESS` | `payouts.withdrawal.success` |
| `FAILED` | `payouts.withdrawal.failed` |
| `EXPIRED` | `payouts.withdrawal.expired` |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.