Payout Subaccount

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:

Real-time wallet funding
Support for transactions in NGN, USD, EUR and GBP currencies
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.

Note that some endpoints require approval before they can be used. If you need access to these endpoints, please send an email to hi@flutterwavego.com 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:

Create a new wallet for your customer by providing their details eg email_address
Issue a virtual account for the wallet.
Fund the wallet by making transfers to the virtual account.
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.

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

{
  "account_name": "John Doe",
  "email": "developers@flutterwavego.com",
  "mobilenumber": "0xxxxxxxx94",
  "country": "NG"
}

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

{
  "status": "success",
  "message": "Payout subaccount created",
  "data": {
    "id": 699,
    "account_reference": "PSAFF2118D1A33844332",
    "account_name": "Flutterwave Developers",
    "barter_id": "234xxxxxxxx94",
    "email": "developers@flutterwavego.com",
    "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
  }
}

Funding Your Wallet via a Virtual Account

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 this link.
ACH payments are not supported for USD wallet funding.

Managing Wallets

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

Making wallet withdrawals

Withdrawing funds from your wallet is easy. You need to provide the beneficiary details and transfer 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": "developers@flutterwavego.com",
  "mobilenumber": "010101010",
  "country": "NG"
}

Making Payments