Withdraw from wallet

{
    "amount": 5000,
    "bank_name": "Access Bank",
    "account_name": "John Doe",
    "account_number": "0690000004",
    "currency": "NGN"
}

{
    "status": "success",
    "message": "Withdrawal request created successfully.",
    "data": {
        "withdrawalRequest": {
            "_id": "665f0c2e9a1b2c0012ab34cd",
            "owner": "64a1f0b39a1b2c0012aa11bb",
            "owner_model": "organisation",
            "reference": "GETXN_PAYOUT_8F3KD9ZQ2",
            "amount": 5000,
            "disburse_amount": 4975,
            "fee": 25,
            "gusd_amount": 1,
            "internal_fee": 0,
            "internal_fee_type": "NONE",
            "currency": "NGN",
            "bank": "665f0c2e9a1b2c0012ab3400",
            "status": "Pending",
            "actioned_on": null,
            "createdAt": "2026-07-04T10:15:42.001Z",
            "updatedAt": "2026-07-04T10:15:42.001Z"
        },
        "bank": {
            "_id": "665f0c2e9a1b2c0012ab3400",
            "name": "Access Bank",
            "code": "044",
            "account_number": "0690000004",
            "account_name": "JOHN DOE",
            "currency": "NGN"
        }
    }
}

{
    "status": "failed",
    "message": "Insufficient NGN balance. Available: 1200, requested: 5000."
}

POST

api

wallet

withdraw

{
    "amount": 5000,
    "bank_name": "Access Bank",
    "account_name": "John Doe",
    "account_number": "0690000004",
    "currency": "NGN"
}

{
    "status": "success",
    "message": "Withdrawal request created successfully.",
    "data": {
        "withdrawalRequest": {
            "_id": "665f0c2e9a1b2c0012ab34cd",
            "owner": "64a1f0b39a1b2c0012aa11bb",
            "owner_model": "organisation",
            "reference": "GETXN_PAYOUT_8F3KD9ZQ2",
            "amount": 5000,
            "disburse_amount": 4975,
            "fee": 25,
            "gusd_amount": 1,
            "internal_fee": 0,
            "internal_fee_type": "NONE",
            "currency": "NGN",
            "bank": "665f0c2e9a1b2c0012ab3400",
            "status": "Pending",
            "actioned_on": null,
            "createdAt": "2026-07-04T10:15:42.001Z",
            "updatedAt": "2026-07-04T10:15:42.001Z"
        },
        "bank": {
            "_id": "665f0c2e9a1b2c0012ab3400",
            "name": "Access Bank",
            "code": "044",
            "account_number": "0690000004",
            "account_name": "JOHN DOE",
            "currency": "NGN"
        }
    }
}

{
    "status": "failed",
    "message": "Insufficient NGN balance. Available: 1200, requested: 5000."
}

Debits the calling organisation’s own currency wallet. The request is created as Pending and the tokens are moved into escrow; it still needs to be approved before funds are disbursed. A withdrawal.created webhook is emitted. disburse_amount = amount − fee, where fee is the withdrawal fee from your *_WITHDRAWAL_FEE config.

{
    "amount": 5000,
    "bank_name": "Access Bank",
    "account_name": "John Doe",
    "account_number": "0690000004",
    "currency": "NGN"
}

amount

number

required

The amount to withdraw. Must be ≥ 1, ≤ your currency wallet balance, and ≥ MINIMUM_WITHDRAWAL_<CUR>.

bank_name

string

required

Matched against Flutterwave’s bank list to resolve the code — pass the full name (e.g. Guaranty Trust Bank, not GTBank).

account_name

string

required

The account holder’s name. For NGN it is replaced with Flutterwave’s resolved name when available.

account_number

string

required

The destination account number.

currency

string

required

The withdrawal currency. One of NGN, KES, GHS, ZAR, UGX, TZS.

{
    "status": "success",
    "message": "Withdrawal request created successfully.",
    "data": {
        "withdrawalRequest": {
            "_id": "665f0c2e9a1b2c0012ab34cd",
            "owner": "64a1f0b39a1b2c0012aa11bb",
            "owner_model": "organisation",
            "reference": "GETXN_PAYOUT_8F3KD9ZQ2",
            "amount": 5000,
            "disburse_amount": 4975,
            "fee": 25,
            "gusd_amount": 1,
            "internal_fee": 0,
            "internal_fee_type": "NONE",
            "currency": "NGN",
            "bank": "665f0c2e9a1b2c0012ab3400",
            "status": "Pending",
            "actioned_on": null,
            "createdAt": "2026-07-04T10:15:42.001Z",
            "updatedAt": "2026-07-04T10:15:42.001Z"
        },
        "bank": {
            "_id": "665f0c2e9a1b2c0012ab3400",
            "name": "Access Bank",
            "code": "044",
            "account_number": "0690000004",
            "account_name": "JOHN DOE",
            "currency": "NGN"
        }
    }
}

{
    "status": "failed",
    "message": "Insufficient NGN balance. Available: 1200, requested: 5000."
}

Errors

HTTP	Message (example)	When
400	`Insufficient NGN balance. Available: 1200, requested: 5000.`	Wallet balance < amount (checked before anything else).
400	`Cannot withdraw less than 1000 NGN`	Below `MINIMUM_WITHDRAWAL_<CUR>`.
400	`child "Currency" fails because ["Currency" must be one of [NGN, KES, GHS, ZAR, UGX, TZS]]`	Unsupported/invalid currency.
400	`Withdrawals with automatic bank resolution are not supported for USD. Supported currencies: NGN, GHS, KES, ZAR, UGX, TZS.`	Currency has no Flutterwave bank list.
404	`Could not find a bank matching "Acess Bank" for NGN. Please check the bank name and try again.`	`bank_name` didn’t match Flutterwave’s list.
502	`Could not fetch the bank list from our payment provider. Please try again later.`	Flutterwave banks call failed.

Fund wallet Get All Currencies Wallet Balance

API Documentation

API Endpoints

Webhook

Withdraw from wallet

Errors

​Errors

Errors