> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ladder.africa/llms.txt
> Use this file to discover all available pages before exploring further.

# Withdrawals

> Send money from your wallet to your own verified settlement account. Debited at once, approved by Ladder, paid by bank transfer.

A withdrawal moves money from a wallet to one of your organisation's settlement accounts in the same currency. Ladder sets those accounts up and verifies them during [onboarding](https://docs.ladder.africa/guides/onboarding.md); `GET /kyb/settlement-accounts` lists them with their `id`.

```json Request theme={null}
{"currency": "NGN", "amount": "400", "settlement_account_id": "62641cf3-a929-4824-bfe5-411d230e9c86"}
```

```json Response (sandbox) theme={null}
{
  "data": {
    "id": "f799cc5d-e835-473c-b891-25cfaaafa8d8",
    "reference": "LPW_46cca9f3bbc941e8b6b9",
    "status": "completed",
    "currency": "NGN",
    "amount": "400.0000",
    "fee": "0.0000",
    "settlement_account_id": "62641cf3-a929-4824-bfe5-411d230e9c86",
    "payout_reference": "SANDBOX",
    "failure_reason": "",
    "approved_at": "2026-11-03T16:03:43.285620",
    "resolved_at": "2026-11-03T16:03:43.285620",
    "created_at": "2026-11-03T16:03:43.279135"
  }
}
```

## How it moves

**1. You request it**

`POST /withdrawals`. The wallet is debited immediately (a `withdrawal_hold` line in `GET /transactions`), so the same money cannot also pay for an order while the withdrawal waits. If the wallet is short you get `402 insufficient_funds` and nothing is created. Status `pending_approval`; `withdrawal.created` is sent.

**2. Ladder approves it**

Every withdrawal is approved by Ladder before money moves. Status `approved`.

**3. Ladder pays it**

Ladder pays the account by bank transfer and records the bank reference. Status `completed`, `payout_reference` set, `withdrawal.completed` sent.

If Ladder rejects the withdrawal (`rejected`, `withdrawal.rejected`) or the transfer cannot be made (`failed`, `withdrawal.failed`), the amount is credited back to the wallet once (`withdrawal_reversal`) and `failure_reason` says why.

## Rules

* The account must be yours, in the withdrawal's currency (`400 settlement_account_currency_mismatch` otherwise), and verified by Ladder (`409 settlement_account_not_verified`).
* There is no withdrawal fee; `fee` is `0`.
* Retrying a request with the same `Idempotency-Key` returns the original withdrawal; the wallet is debited once.
* With test keys a withdrawal completes immediately with `payout_reference` `SANDBOX`.

`GET /withdrawals` lists them (filter with `status`); `GET /withdrawals/{id}` returns one.


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