DocumentationAPI ReferencesSupportBlogCustom #
Documentation

Payout Subaccount

Create virtual wallets for your customers with Flutterwave.

Suggest Edits

The payout subaccounts feature enables you to create wallets linked to your Flutterwave account for your end users, consumers, or other entities. These wallets only support payments in NGN. This means that you can use the wallets to manage balances on behalf of your consumers for online transactions.
Some of the key features of these wallets include:

  1. Real-time wallet funding
  2. Support for NGN transaction.
  3. Interoperability with withdrawals to bank accounts, mobile money, and other wallet systems.

Prerequisites

Before integrating, make sure that your account is live for production API calls.


Wallet Setup

The wallets are designed to hold only NGN balances.

Each wallet has a dedicated virtual account assigned to it, making it possible to fund your wallet. For example, you can fund your NGN wallet balance by transferring to your NGN virtual account number.
When you create a Flutterwave account, you automatically get a super wallet. To create a new wallet, pass your customer's details to the create PSA wallet endpoint. This automatically creates an NGN wallet. The overview below outlines the important steps to successfully create and manage your wallets:

  1. Create a new wallet for your customer by providing their details e.g. name, countryand email_address.
  2. Issue a virtual account for the wallet.
  3. Fund the wallet by making transfers to the virtual account.
  4. Manage the balances and customer details associated with the wallet.

Wallet Creation

To create a wallet for your customer, send the wallet name and the customer's details (email address and country) to the wallet creation endpoint. You also have the option of specifying either WEMA(035) or Sterling(232) bank as the primary bank associated with the default account linked to the customer's wallet.

{
   "account_name":"Lebron james",
   "email":"[email protected]",
   "country":"NG",
   "bank_code":"035"
}

On creating the wallet, you will receive a successful response:

{
    "status": "success",
    "message": "Payout subaccount created",
    "data": {
        "id": 453748,
        "account_reference": "PSA14B6C11AE18421012",
        "account_name": "Lebron James",
        "barter_id": "234000003363471",
        "email": "[email protected]",
        "country": "NG",
        "nuban": "7353333250",
        "bank_name": "Wema Bank PLC",
        "bank_code": "035",
        "status": "ACTIVE",
        "created_at": "2025-08-26T11:40:27.000Z"
    }
}

Issue Virtual Account

After creating your wallet, you will need to issue a virtual account that can be used to fund it.

To issue a virtual account, pass the account reference to the fetch static account endpoint .

{
    "status": "success",
    "message": "SERVICE-RESPONSE",
    "data": {
        "static_account": "8523283309",
        "bank_name": "Sterling Bank PLC",
        "bank_code": "232",
        "currency": "NGN"
    }
}

For every transfer made into the virtual account, you will receive a webhook notification with the details of the transaction in the following structure:

{
            "event": "transfer.completed",
            "event.type": "Transfer",
            "data": {
                "id": 85677894,
                "account_number": "9461801496",
                "bank_name": "Wema Bank PLC",
                "bank_code": "035",
                "fullname": "ID AGBA",
                "created_at": "2024-10-31T04:30:08.000Z",
                "currency": "NGN",
                "debit_currency": "PSA",
                "amount": "200000",
                "fee": "2,000.00",
                "status": "SUCCESSFUL",
                "reference": "PSA_100004241030233238121386040596",
                "meta": null,
                "narration": "WALLET FUNDING",
                "approver": null,
                "complete_message": "",
                "requires_approval": 0,
                "is_approved": 1
            }
        }

Wallet Funding

After creating your virtual accounts, you or end-users will need to transfer funds from your preferred bank to your wallet to fund it.
Alternatively, you can fund your PSA wallet using wallet-to-wallet transfers. Here is a sample to guide your funding using internal transfers:

// HTTP Verb: POST
// Endpoint: v3/transfers
// Header:
{
    "Authorization": Bearer <YOUR_SECRET_KEY>
}
// Body
{
    "account_bank": "flutterwave",
    "account_number": "234000002637748",//Destination wallet's barter id(data.barter_id)
    "amount": 10000,
    "currency": "NGN"

}

Response should look like this:

{
    "status": "success",
    "message": "Transfer Queued Successfully",
    "data": {
        "id": 2024116,
        "account_number": "49851890",
        "bank_code": "flutterwave",
        "full_name": "PAYOUTSUB Lebron James",
        "created_at": "2025-08-26T12:31:01.000Z",
        "currency": "NGN",
        "debit_currency": "NGN",
        "amount": 10000,
        "fee": 0,
        "status": "NEW",
        "reference": "9833d05412688b4a",
        "meta": {
            "AccountId": 2637748,
            "merchant_id": "234000002637748"
        },
        "narration": "From Dotuns Fashion Limited",
        "complete_message": "",
        "requires_approval": 0,
        "is_approved": 1,
        "bank_name": "wallet"
    }
}

🚧

Storing Wallet Information

For easy wallet funding, You'll need to store your wallet's barter_id and account_reference. We return these details after you create a new wallet.

{
    "status": "success",
    "message": "Payout subaccount created",
    "data": {
        "id": 42,
        "account_reference": "PSA0F18FC37993794182",
        ...
        "barter_id": "234007249611996",
        ...
    }
}

Mocking Wallet Funding

In test mode, you can simulate wallet funding. Follow the example below to mock your wallet funding:

// HTTP Verb: POST
// Endpoint: /v3/payout-subaccounts/:account_reference/fund-account
// Header: 
{
    "Authorization": Bearer <YOUR_SECRET_KEY>
}
// Body
{
    "currency": "",
    "amount": ""
}

// https://api.flutterwave.com/v3/payout-subaccounts/PSA0F18FC37993794182/fund-account
{
    "currency": "NGN",
    "amount": "5500"
}

Sample response:

{
	"status": "success",
	"message": "Successfully funded NGN wallet.",
	"data": null
}

Managing Wallets

Now that you have created a virtual account for your wallet, Your customers can now fund their wallets. You can manage your wallets with these operations:

  1. Withdraw funds from a user's wallet.
  2. Query a wallet's balance.
  3. Fetch a wallet's transactions.
  4. Update wallet details.
  5. Deleting Wallets

Making Wallet Withdrawals

Withdrawing funds from your wallet is easy. You need to provide the beneficiary details and transfer the amount to the create transfer endpoint. It is important to include the debit_subaccount parameter. This will let us know which wallet to debit for the withdrawals. There are three destinations available for withdrawals:

  • Bank Account Withdrawals: These withdrawals are made to the Customer's Bank account.
  • PSA Withdrawals: With this type of withdrawal, funds are transferred into another PSA account that you create.
  • Withdrawals to F4B Account: This type of withdrawal is made into your main F4B account. To ensure a successful transaction, you'll need to specify your F4B account.
{
	"account_bank": "044",
	"account_number": "0690000040",
	"amount": 5500,
	"narration": "Akhlm Pstmn Trnsfr xx007",
	"currency": "NGN",
	"reference": "YOUR_PAYMENT_REFERENCE",
	"callback_url": "https://www.flutterwave.com/ng/",
	"debit_currency": "NGN",
	"debit_subaccount": "PSAFF2118D1A33844332"
}

{
    "account_bank": "flutterwave",
    "account_number": "PSA_BARTER_ID" //this is the identifier returned as `data.barter_id` when creating the PSA,
    "amount": 200,
    "currency": "USD",
    "debit_currency": "NGN",
    "reference": "YOUR_PAYMENT_REFERENCE",
    "debit_subaccount": "PSAFF2118D1A33844332"
}

{
    "account_bank": "flutterwave",
    "account_number": "YOUR_MERCHANT_ID" //This is your account identifier. You can find it in your dashboard,
    "amount": 200,
    "currency": "NGN",
    "debit_currency": "USD",
    "reference": "pay-{{$timestamp}}"
}

Managing Wallet Details

If you need information on your wallets, you can use the fetch wallet to get the wallet's data. With this endpoint, you can quickly and efficiently retrieve the paginated data. Even if you have a lot of wallets, you can easily filter the data using the cursor_pointer and limit parameters.

curl --request GET \
  --url 'https://api.flutterwave.com/v3/payout-subaccounts?limit=10&next_cursor=923' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer FLWSECK_TEST-SANDBOXDEMOKEY-X' \
  --header 'Content-Type: application/json'

To review your transaction data (funding and withdrawal logs) and check your wallet's balance, call the transaction query endpoint. Remember to check your user's balance before making any transfers or withdrawals.

	curl --request GET \
  --url 'https://api.flutterwave.com/v3/payout-subaccounts/WALLET_REFERENCE/transactions?from=2025-08-01&to=2025-08-20' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer FLWSECK_TEST-SANDBOXDEMOKEY-X' \
  --header 'Content-Type: application/json'
	```
 

curl --request GET \
  --url 'https://api.flutterwave.com/v3/payout-subaccounts/WALLET_REFERENCE/balances' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer FLWSECK_TEST-SANDBOXDEMOKEY-X' \
  --header 'Content-Type: application/json'

Updating your User's Wallet Details

If you ever need to update a user's details, you can do so by passing the data to be added to the update endpoint. Please note that this endpoint only supports updates to the wallet name, mobile number, email address and country.

{
	"account_name": "Flutterwave Developers",
	"email": "[email protected]",
	"mobilenumber": "010101010",
	"country": "NG"
}

Deleting Wallets

Flutterwave allows you to delete wallets that are unused or linked with customers who no longer use your service.

Before deleting a wallet, keep these points in mind:

  1. You won’t be able to fetch static virtual accounts for a deleted wallet. Instead, you’ll receive the message "Invalid Account Reference.".
  2. Deleted wallets cannot be re-enabled.
  3. Transfers to deleted wallets won’t be processed and will be returned to the sender's account.

To delete a customer's wallet, send a DELETE request to our Delete PSA Endpoint using the wallet's “account_reference”.

curl --location --request DELETE 'https://api.flutterwave.com/v3/payout-subaccounts/WalletAccountReference' \
--header 'Authorization: Bearer FLWSECK_TEST-SANDBOXDEMOKEY-X' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json'

A Successful Response should look like this:

{
    "status": "success",
    "message": "Payout sub-account deactivation has been submitted for processing.",
    "data": null
}

Updated 1 day ago