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

# Troubleshooting: payout stuck in pending

> Why a payout sits in pending or processing, how to tell a funding delay from a real failure, and what to check before contacting support.

A payout that stays in `PENDING_ADDRESS_DEPOSIT` is almost always waiting on one thing: funding. This page walks through what each status actually means, where payouts commonly stall, and how to confirm final state instead of guessing.

## What the statuses mean

| Status | Meaning |
| - | - |
| `PENDING_ADDRESS_DEPOSIT` | Initialized and awaiting your onchain deposit. |
| `PENDING` | Finalized and queued for dispatch. |
| `PROCESSING` | Funded; settlement to the beneficiary is in progress. |
| `SUCCESS` | Funds delivered to the beneficiary. |
| `FAILED` | The payout could not be completed. |
| `EXPIRED` | The quote expired before funding arrived. |

`PENDING_ADDRESS_DEPOSIT` is not an error state. It is the normal resting state of an onchain payout that has not been funded yet.

## Cause 1: the payout was never funded

For **offchain** payouts, your account balance is charged at finalize. If finalize succeeded, the payout proceeds automatically and should move to `PROCESSING` quickly.

For **onchain** payouts, nothing happens until your crypto deposit arrives at the address returned during initialization. The payout waits in `PENDING_ADDRESS_DEPOSIT` until:

* the deposit confirms on-chain (BTC), or
* the Lightning payment settles, or
* the stablecoin deposit confirms.

**Check:** sandbox has no endpoint that simulates a crypto deposit for a payout. An onchain payout you haven't funded stays in `PENDING_ADDRESS_DEPOSIT`. That's expected behavior, not a bug.

## Cause 2: you are reading the wrong status field

Webhook payloads and status lookups do not always use the same vocabulary for the same state. If your code compares a webhook's `data.status` value against the values documented for [Get payout](https://www.bitnob.dev/api-reference/payouts/get-payout.md), a valid transition can look like "no change" to your system even though the payout moved forward.

**Check:** log the raw webhook body and the raw response from `GET /api/payouts/{id}` side by side for the same payout. Map both vocabularies explicitly in your integration rather than assuming they match.

## Cause 3: it is genuinely still processing

Settlement to banks and mobile-money operators is not instant and varies by corridor. A payout in `PROCESSING` is funded and moving; there is nothing to retry.

**Check:** poll `GET /api/payouts/{id}` or rely on webhooks at your `callback_url`. Treat `SUCCESS` as the only success state and confirm it via lookup or webhook rather than assuming success from the finalize response.

## Escalating to support

If a payout has been in `PENDING_ADDRESS_DEPOSIT` well past your deposit's confirmation, or in `PROCESSING` far longer than the corridor's normal settlement time, contact support with:

* the payout `reference` you set at initialization,
* the `correlation_id` from the relevant API error response,
* the quote ID and, for onchain payouts, the deposit transaction hash.


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