Split payments (subaccounts)

Overview

Flutterwave's split payments feature allows you to split an incoming payment between one or more bank accounts and a commission fee. This can be useful in many ways, for example:

You act as an aggregator where you manage payments for different entities, in exchange for a commission.
You run a marketplace where different vendors provide services, while you handle payments and collect a commission on each transaction.

To use split payments, you'll need to first set up one or more subaccounts (the bank accounts you want to split to). Then when collecting payment, you can specify how you would like to split the money. Any funds you direct to them will be settled into their account based on your settlement cycle.

Your merchants are your responsibility

When using this feature, you (the marketplace owner) are responsible for vetting the merchants signed up under your marketplace. Any disputes and chargebacks will be logged against your account, so endeavour to have reliable merchants and proper processes in place.

Creating subaccounts

You can create subaccounts easily from your dashboard. Alternatively, you can use the create subaccount endpoint. You'll need to supply these details:

account_bank and account_number: The bank account details for this subaccount. The acccount_bank is the bank code (which you can get from the get banks endpoint).

When in Test Mode, you can use any of our test account numbers for your subaccount.
country: The country the bank account is in.
business_name and business_mobile: Details about the vendor/merchant the subaccount is for.
split_type: The type of split you want to use with this subaccount.
- Use "percentage" if you want to get a percentage of each transaction.
- Use "flat" if you want to get a flat fee from each transaction, while the subaccount gets the rest.
split_value: The amount you want to get as commission on each transaction. This goes with the split_type, for example:
- to collect 9% from each transaction, split_type will be "percentage" and split_value will be 0.09
- to collect 600 naira from each transaction, split_type will be "flat" and split_value will be 600

The split_type and split_value are the default rules for splitting payments into this subaccount, but you can also override them for each transaction.

We'll use "naira(NGN)" in this article, but subaccounts work the same regardless of the currency the transaction is in.

Here are some examples with our backend SDKs:

// Install with: npm i flutterwave-node-v3

const Flutterwave = require('flutterwave-node-v3');
const flw = new Flutterwave(process.env.FLW_PUBLIC_KEY, process.env.FLW_SECRET_KEY);
const details = {
   account_bank: "044",
   account_number: "0690000037",
   business_name: "Flutterwave Developers",
   business_mobile: "09087930450",
   country: "NG",
   split_type: "percentage",
   split_value: 0.2
};
flw.Subaccount.create(details)
  .then(console.log)
  .catch(console.log);

// Install with: composer require flutterwavedev/flutterwave-v3

$flw = new \Flutterwave\Rave(getenv('FLW_SECRET_KEY')); // Set `PUBLIC_KEY` as an environment variable
$subaccountService = new \Flutterwave\Subaccount();
$details = array(
    "account_bank"=> "044",
    "account_number"=> "0690000037",
    "business_name"=> "Flutterwave Developers",
    "business_mobile"=> "09087930450",
    "country"=> "NG",
    "split_type"=> "percentage",
    "split_value"=> 0.2
);
$response = $subaccountService->createSubaccount($details);

# Install with: gem install flutterwave_sdk

require 'flutterwave_sdk'

flw = Flutterwave.new(ENV["FLW_PUBLIC_KEY"], ENV["FLW_SECRET_KEY"], ENV["FLW_ENCRYPTION_KEY"])
subaccount = Subaccount.new(flw)
details = {
   account_bank: "044",
   account_number: "0690000037",
   business_name: "Flutterwave Developers",
   business_mobile: "09087930450",
   country: "NG",
   split_type: "percentage",
   split_value: 0.2
}
response = subaccount.create_subaccount details
print response

# Install with: pip install rave_python

import os
from rave_python import Rave

rave = Rave(os.getenv("FLW_PUBLIC_KEY"), os.getenv("FLW_SECRET_KEY"))
details = {
 "account_bank": "044",
 "account_number": "0690000037",
 "business_name": "Flutterwave Developers",
 "business_mobile": "09087930450",
 "country": "NG",
 "split_type": "percentage",
 "split_value": 0.2
}
response = rave.SubAccount.create(details)
print(response)

// Install with: go get github.com/Flutterwave/Rave-go/rave

import (
  "fmt"
  "os"
  "github.com/Flutterwave/Rave-go/rave"
)
var r = rave.Rave{
  false,
  os.Getenv("FLW_PUBLIC_KEY"),
  os.Getenv("FLW_SECRET_KEY"),
}
var subaccoun = rave.Subaccoun{
    r,
}
details := rave.CreateSubaccountData{
        AccountBank: "044",
        AccountNumber: "0690000035",
        BusinessName: "Flutterwave Developers",
        BusinessMobile: "09087930123",
        SplitType: "percentage",
        SplitValue: "0.2",
    }
err, response := subaccoun.CreateSubaccoun(details)
if err != nil {
    panic(err)
}
fmt.Println(response)

curl --request POST 'https://api.flutterwave.com/v3/accounts/resolve' \
  --header 'Authorization: Bearer YOUR_SECRET_KEY'\
  --header 'Content-Type: application/json'\
  --data-raw '{
   "account_bank": "044",
   "account_number": "0690000037",
   "business_name": "Flutterwave Developers",
   "business_mobile": "09087930450",
   "country": "NG",
   "split_type": "percentage",
   "split_value": 0.2
}'

Country-specific requirements

For certain countries, you'll also need to include a meta object containing additional information about the bank account.

If the account is in the US, you'll need to supply a Swift code and routing number. If it's in Ghana, Tanzania, Rwanda, Uganda, or Tanzania, you'll need to supply a branch code.

{
  //...
  country: "US"
  meta: [
    {
      swiftCode: "USMMI120"
    },
    {
      routingNumber: "121212121"
    }
  ]
}

{
  //...
  country: "UG"
  meta: [
    {
      swiftCode: ""
    },
    {
      bank_branch: "UG301847"
    }
  ]
}

You'll get a response like this:

{
  "status": "success",
  "message": "Subaccount created",
  "data": {
    "id": 9530,
    "account_number": "0690000037",
    "account_bank": "044",
    "full_name": "Ibra Mili",
    "created_at": "2021-04-21T10:43:24.000Z",
    "meta": [],
    "split_type": "percentage",
    "split_value": 0.2,
    "subaccount_id": "RS_FB312AA6C2C84A13421F3079E714F2CB",
    "bank_name": "ACCESS BANK NIGERIA"
  }
}

{
  "status": "error",
  "message": "A subaccount with the account number and bank already exists",
  "data": null
}

The important value here is the data.subaccount_id. You'll use this when you want to split payments into that subaccount.

Using subaccounts

Now that you've created a subaccount, you can split payments with it by specifying the ID whenever you're collecting payments. This applies across our different integration options, including Flutterwave Inline, Standard, HTML checkout, and direct card charge).

To specify how the payment should be split across subaccounts, define a subaccounts field. The subaccounts field holds an array of subaccount objects, each containing the ID of the subaccount, returned from the create subaccount call or as displayed in your dashboard.

<script>
  function makePayment() {
    FlutterwaveCheckout({
      // ...
      amount: 54600,
      currency: "NGN",
      subaccounts: [
        {
          id: "RS_A8EB7D4D9C66C0B1C75014EE67D4D663",
        }
      ],
    });
  }
</script>

// require('flutterwave-node-v3');

const payload = {
  // ...
  card_number: '4556052704172643',
  amount: 54600,
  currency: "NGN",
  subaccounts: [
    {
      id: "RS_A8EB7D4D9C66C0B1C75014EE67D4D663",
    }
  ],
};
var response = await flw.Charge.card(payload);

// use Flutterwave\Card;

$data = array(
  // ...
  "card_number"=> "5531886652142950",
  "currency"=> "NGN",
  "amount" => "1000",
  "subaccounts" => [
    {
      id: "RS_A8EB7D4D9C66C0B1C75014EE67D4D663",
    }
  ],
);

$payment = new Card();
$response = $payment->cardCharge($data);

# require 'flutterwave_sdk'

payload = {
  # ...
  "card_number"=> "5531886652142950",
  "currency"=> "NGN",
  "amount" => "1000",
  "subaccounts" => [
    {
      id: "RS_A8EB7D4D9C66C0B1C75014EE67D4D663",
    }
  ]
}

charge_card = Card.new(payment)
response = charge_card.initiate_charge(payload)

# from rave_python import Rave

payload = {
  # ...
  card_number: '4556052704172643',
  amount: 54600,
  currency: "NGN",
  subaccounts: [
    {
      id: "RS_A8EB7D4D9C66C0B1C75014EE67D4D663",
    }
  ],
}
response = rave.Card.charge(payload)

Overriding the defaults

When collecting a payment, you can override the default split_type and split_value you set when creating the subaccount, by specifying these fields in the subaccounts item:

transaction_charge_type: The type of commission to charge for this transaction:
- "flat_subaccount" if you want the subaccount to get a flat fee from this transaction while you get the rest.
- "flat" if you want to get a flat fee while the subaccount gets the rest, or
- "percentage" if you want to get a percentage of the settlement amount.
transaction_charge: The amount to charge as commission on the transaction. This should match with the transaction_charge_type, for example:
- to collect a 9% commission, transaction_charge_type will be "percentage" and transaction_charge will be 0.09
- to collect a 600 naira commission, transaction_charge_type will be "flat" and transaction_charge will be 600
- to give the subaccount 4200 naira from this transaction while you get whatever's left, transaction_charge_type will be "flat_subaccount" and transaction_charge will be 4200

Here are some examples. In each of these transactions, let's suppose the whole amount paid is 6000 naira and Flutterwave fees are 60 naira.

subaccounts: [
  {
    id: "RS_A8EB7D4D9C66C0B1C75014EE67D4D663",
    // If you want the subaccount to get 4200 naira only
    // Subaccount gets: 4200
    // You get: 6000 - 4200 - 60 = 1740
    transaction_charge_type: "flat_subaccount",
    transaction_charge: 4200,
  },
],

subaccounts: [
  {
    id: "RS_A8EB7D4D9C66C0B1C75014EE67D4D663",
    // If you want to get 400 naira as commission
    // Subaccount gets: 6000 - 400 - 60 = 5540
    // You get: 400
    transaction_charge_type: "flat",
    transaction_charge: 400,
  },
],

subaccounts: [
  {
    id: "RS_A8EB7D4D9C66C0B1C75014EE67D4D663",
    // If you want to get 20% of the transaction as commission
    // You get: (0.2 * 6000) = 1200
    // Subaccount gets: 6000 - 1200 - 60 = 4740
    transaction_charge_type: "percentage",
    transaction_charge: 0.2,
  },
],

Splitting across multiple subaccounts

If you're splitting a payment between multiple subaccounts, you can specify a transaction_split_ratio that defines how the money (excluding your commission and Flutterwave fees) is shared proportionally.

For example, let's suppose you're splitting a payment between 3 vendors. Let's say you want a commission of 300 naira, and the vendors should share what's left:

vendor A should get 20% of the payment
vendor B should get 30% of the payment
vendor C should get the remaining 50%

This means your split ratio will be 2:3:5. So your subaccounts array would look like this:

      subaccounts: [
        {
          // vendor A
          id: "RS_D87A9EE339AE28BFA2AE86041C6DE70E",
          transaction_split_ratio: 2,
          transaction_charge_type: "flat",
          transaction_charge: 100,
        },
        {
          // vendor B
          id: "RS_344DD49DB5D471EF565C897ECD67CD95",
          transaction_split_ratio: 3,
          transaction_charge_type: "flat",
          transaction_charge: 100,
        },
        {
          // vendor C
          id: "RS_839AC07C3450A65004A0E11B83E22CA9",
          transaction_split_ratio: 5,
          transaction_charge_type: "flat",
          transaction_charge: 100,
        },
      ],

Assuming the total payment is 16,000 naira, and Flutterwave fees are 200 naira, this means:

you'll get 300 naira (100 naira flat commission from each subaccount)
the settlement amount (the amount the subaccounts will split) is 15,500 (16000 - 200 - 300)
vendor A will get 3,100 ((2/(2+3+5) * 15500)
vendor A will get 4,650 ((3/(2+3+5) * 15500)
vendor A will get 7,750 ((5/(2+3+5) * 15500)

Stamp duties on split payment

For transactions above NGN 10,000, a CBN stamp duty fee of NGN 50 will be charged and debited from the settlement amount. If you set up your subaccount to receive a flat amount and your settlement amount is less than the flat amount, there will not be a split payment. Instead, the entire settlement amount will be sent to your main account.

For example, if you receive a transaction of NGN 15,000 and your subaccount is set to set to receive a flat amount of NGN 14,960, your subaccount will not be able to receive any amount for this transaction.

This is because after the CBN stamp duty of NGN 50 is debited, your settlement will become NGN 14,950 which is less than what you’ve set for the subaccount to receive. In a case like this, your settlement will be sent to your main account.

Learn more

If you need more details about splitting payments, this article goes through several possible scenarios when splitting payments across subaccounts.

To learn more about managing subaccounts with our API, check out the API reference. If you get lost, feel free to ask a question on our developer forums.

Collecting Payments