Withdrawals

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; GET /kyb/settlement-accounts lists them with their id.

Request

{"currency": "NGN", "amount": "400", "settlement_account_id": "62641cf3-a929-4824-bfe5-411d230e9c86"}

Response (sandbox)

{
  "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

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.

Ladder approves it

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

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.

Getting started

The journey

Reference

How it moves

Rules

​How it moves

​Rules

How it moves

Rules