{
"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": "665f0c2e9a1b2c0012ab77ef",
"owner": "651bd2a49a1b2c0012cc55dd",
"owner_model": "user",
"reference": "GETXN_PAYOUT_K92JD0PLM",
"amount": 5000,
"disburse_amount": 4500,
"fee": 500,
"currency": "NGN",
"bank": "665f0c2e9a1b2c0012ab7700",
"status": "Pending",
"actioned_on": null,
"createdAt": "2026-07-04T10:18:10.442Z",
"updatedAt": "2026-07-04T10:18:10.442Z"
},
"bank": {
"_id": "665f0c2e9a1b2c0012ab7700",
"name": "Access Bank",
"code": "044",
"account_number": "0690000004",
"account_name": "JOHN DOE",
"currency": "NGN"
}
}
}
{
"status": "failed",
"message": "Insufficient NGN balance. Available: 1200, requested: 5000."
}
Members
Withdraw from member wallet
Debit a member’s currency wallet to a bank account
POST
api
/
members
/
{id}
/
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": "665f0c2e9a1b2c0012ab77ef",
"owner": "651bd2a49a1b2c0012cc55dd",
"owner_model": "user",
"reference": "GETXN_PAYOUT_K92JD0PLM",
"amount": 5000,
"disburse_amount": 4500,
"fee": 500,
"currency": "NGN",
"bank": "665f0c2e9a1b2c0012ab7700",
"status": "Pending",
"actioned_on": null,
"createdAt": "2026-07-04T10:18:10.442Z",
"updatedAt": "2026-07-04T10:18:10.442Z"
},
"bank": {
"_id": "665f0c2e9a1b2c0012ab7700",
"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 a member’s currency wallet (the member is identified by
Treat the
id in the path). The request is created as Pending and the tokens are moved into escrow; it still needs to be approved before funds are disbursed.
The balance and escrow are the member’s, and owner_model is user (versus organisation for the organisation withdrawal). The withdrawal.created webhook still fires to your organisation.
Fees
The fee is taken out of the amount, not added on top — so the member receives less than they asked for, and your interface should say so before they confirm.disburse_amount = amount − fee
| Currency | Fee |
|---|---|
| NGN | ₦500 flat, per withdrawal, regardless of amount |
fee and disburse_amount fields on the response as authoritative rather than
hard-coding the figure — fees change without an API version bump. A withdrawal for less than the
fee is rejected with Insufficient amount for fees.
{
"amount": 5000,
"bank_name": "Access Bank",
"account_name": "John Doe",
"account_number": "0690000004",
"currency": "NGN"
}
The amount to withdraw. Must be ≥ 1, ≤ the member’s currency wallet balance, and ≥
MINIMUM_WITHDRAWAL_<CUR>.Matched against Flutterwave’s bank list to resolve the code — pass the full name (e.g.
Guaranty Trust Bank, not GTBank).The account holder’s name. For NGN it is replaced with Flutterwave’s resolved name when available.
{
"status": "success",
"message": "Withdrawal request created successfully.",
"data": {
"withdrawalRequest": {
"_id": "665f0c2e9a1b2c0012ab77ef",
"owner": "651bd2a49a1b2c0012cc55dd",
"owner_model": "user",
"reference": "GETXN_PAYOUT_K92JD0PLM",
"amount": 5000,
"disburse_amount": 4500,
"fee": 500,
"currency": "NGN",
"bank": "665f0c2e9a1b2c0012ab7700",
"status": "Pending",
"actioned_on": null,
"createdAt": "2026-07-04T10:18:10.442Z",
"updatedAt": "2026-07-04T10:18:10.442Z"
},
"bank": {
"_id": "665f0c2e9a1b2c0012ab7700",
"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. |
| 404 | User not found | Invalid id. |
| 502 | Could not fetch the bank list from our payment provider. Please try again later. | Flutterwave banks call failed. |
Was this page helpful?
