Skip to main content
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

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