DocumentationRecipesAPI ReferencesSupportBlog
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 support payments across multiple currencies, specifically NGN, USD, EUR, and GBP. 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 transactions in NGN, USD, EUR, and GBP currencies
  3. Interoperability with withdrawals to bank accounts, mobile money, and other wallet systems.

Prerequisites

Before integrating, make sure that your account is live and that the feature is enabled.

🚧

Approval Required

Note that some endpoints require approval before they can be used. If you need access to these endpoints, please send an email to [email protected] requesting approval.

Wallet Setup

The wallets are designed to hold four balances: NGN, USD, EUR, and GBP.


Each wallet has a dedicated virtual account assigned to it, making it possible to fund your wallet in that specific currency. For example, you can fund your USD wallet balance by transferring to your USD 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. 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, mobile number, and country) to the wallet creation endpoint.

📘

Wallet and Account

By default, an NGN Wallet and Virtual Account will be created for you.

{
	"account_name": "John Doe",
	"email": "[email protected]",
	"mobilenumber": "0xxxxxxxx94",
	"country": "NG"
}

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

{
	"status": "success",
	"message": "Payout subaccount created",
	"data": {
		"id": 699,
		"account_reference": "PSAFF2118D1A33844332",
		"account_name": "Flutterwave Developers",
		"barter_id": "234xxxxxxxx94",
		"email": "[email protected]",
		"mobilenumber": "0xxxxxxxx94",
		"country": "NG",
		"nuban": "6222126177",
		"bank_name": "Sterling Bank",
		"bank_code": "232",
		"status": "ACTIVE",
		"created_at": "2022-03-04T19:57:24.000Z"
	}
}

Issue Virtual Account

After creating your wallet, you will need to issue a virtual account that can be used to fund it. By default, an NGN virtual account is automatically created and linked to your wallet. To receive inflow into other wallet balances, you will need to issue a virtual account in the corresponding currency. For example, to receive USD inflow, you will need a USD virtual account.


To issue a virtual account, pass the account reference and preferred currency (USD, EUR, GBP) to the fetch static account endpoint.

{
	"status": "success",
	"message": "SERVICE-RESPONSE",
	"data": {
		"static_account": "8336657404",
		"bank_name": "Community Federal Savings Bank",
		"bank_code": "026073150",
		"currency": "USD",
		"is_default": null,
		"type": "ach_routing_number"
	}
}

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": 1771111,
		"account_number": "83*****11",
		"bank_name": "Community Federal Savings Bank",
		"bank_code": "02***150",
		"fullname": "PAYPAL;;US;PAYPALRD33;;091000019",
		"created_at": "2021-12-13T14:36:02.000Z",
		"currency": "USD",
		"debit_currency": "PSA",
		"amount": "100.10",
		"fee": 0,
		"status": "SUCCESSFUL",
		"reference": "PSA_9e94ce41-39f5-460b-a0bb-111111111111",
		"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. Follow these guidelines to ensure successful funding of your wallets:

  • When the sending channel requires you to select an account type, choose "checking" (not savings).
  • Please note that not all countries are permitted to send funds to virtual accounts. For a full list of permitted countries, please refer to the link.
  • ACH payments are not supported for USD wallet funding.

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": "234007249611996", //Destination wallet's barter id(data.barter_id).
    "amount": 400,
    "currency": "NGN",
    "narration": "From Flutterwave Developers",
    "debit_subaccount": "PSA001CC9C8D77545950" //Source wallet's account_reference
}

Response should look like this:

{
	"status": "success",
	"message": "Transfer Queued Successfully",
	"data": {
		"id": 646539,
		"account_number": 99992069,
		"bank_code": "flutterwave",
		"full_name": "FLUTTERWAVE V3 DOCS",
		"created_at": "2024-08-06T15:52:49.000Z",
		"currency": "NGN",
		"debit_currency": "NGN",
		"amount": 500,
		"fee": 0,
		"status": "NEW",
		"reference": "c6cab8fb0813d2fd",
		"meta": {
			"AccountId": 118468,
			"merchant_id": "00118468"
		},
		"narration": "From Flutterwave Developers",
		"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.

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=2021-01-01&to=2021-02-10currency=USD' \
  --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?currency=USD' \
  --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, and email address.

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

Updated about 1 month ago