Split Payment

This shows you how to split a payment into multiple Flutterwave subaccounts.

Flutterwave's split payment feature allows you to split a transaction between two (2) or more accounts and collect fees on the transaction. This feature is great for marketplace owners who help facilitate services for merchants and collect a commission as revenue.

Flutterwave can automatically split the settlement such that the vendor's account is credited and the platform owner gets his own commission credited as well.

When using this feature, the marketplace owner is responsible for vetting the merchants signed up under their marketplace, this means that disputes and chargebacks would be logged against the marketplace owner.

We would show you how to create subaccounts on the Flutterwave dashboard and how you can collect payments on behalf of these subaccounts.

📘

Subaccount Account Numbers on Test environment

When setting up test subaccounts, use test account numbers in the test environment.

Make use of account numbers within the range 0690000021 - 0690000041
Bank: 044 (Access bank). Check out our Test bank accounts for more.

How to create subaccounts

Flutterwave allows you to create subaccounts using two methods

a.) Create the subaccount on the dashboard

b.) Through the Flutterwave Inline checkout modal

c.) Create the subaccount using our APIs.

We will demonstrate (a. and (b. on this document. To see how to create subaccounts via APIs visit our reference section Create a subaccount

Create a subaccount via the dashboard

Click on Subaccounts in the left menu bar

Fill in the new subaccount details and click Create New Subaccount

The newly created Subaccount will now appear on your subaccounts listing.

When you create a subaccount you would be using the subaccount ID to refer to that subaccount. You will mostly use it when you want to collect payments for that subaccount.

See how to do that via the Flutterwave inline JS below.

Split to multiple subaccounts

<form>
  <script src="https://checkout.flutterwave.com/v3.js"></script>
  <button type="button" onClick="makePayment()">Pay Now </button>
</form>
<script>
  function makePayment() {
    FlutterwaveCheckout({
      public_key: "YOUR_PUBLIC_KEY",
      tx_ref: "hooli-tx-new-test",
      amount: 54600,
      currency: "NGN",
      payment_options: "card,ussd,qr,barter",
      customer: {
        email: "[email protected]",
        phonenumber: "08102909304",
        name: "Yemi Desola",
      },
      subaccounts: [
        {
          id: "RS_A8EB7D4D9C66C0B1C75014EE67D4D663",
          transaction_split_ratio: 2,
        },
        {
          id: "RS_CF5B2A15E2CCD39F44E7774376EAE5C5",
          transaction_split_ratio: 2,
        },
      ],
      callback: function (data) {
        console.log(data);
      },
      customizations: {
        title: "My store",
        description: "Payment for items in cart",
        logo: "https://assets.piedpiper.com/logo.png",
      },
    });
  }
</script>

Split to One Subaccount

<form>
  <script src="https://checkout.flutterwave.com/v3.js"></script>
  <button type="button" onClick="makePayment()">Pay Now </button>
</form>
<script>
  function makePayment() {
    FlutterwaveCheckout({
      public_key: "YOUR_PUBLIC_KEY",
      tx_ref: "hooli-tx-new-test",
      amount: 54600,
      currency: "NGN",
      payment_options: "card,ussd,qr,barter",
      customer: {
        email: "[email protected]",
        phonenumber: "08102909304",
        name: "Yemi Desola",
      },
      subaccounts: [
        {
          id: "RS_A8EB7D4D9C66C0B1C75014EE67D4D663",// This assumes you have setup your commission on the dashboard.
        }
      ],
      callback: function (data) {
        console.log(data);
      },
      customizations: {
        title: "My store",
        description: "Payment for items in cart",
        logo: "https://assets.piedpiper.com/logo.png",
      },
    });
  }
</script>

The subaccounts are passed to the checkout function as an array of objects. This means you can split payment between more than one vendor and determine the split ratio e.g. If you are splitting the money between 3 vendors and you don't want them to all get equal amounts you can apply a split ratio e.g. 2:3:5.

This split example also means you are splitting the money as 20%, 30%, 50% accordingly. This means the first vendor would get (2/(2+3+5) x (total amount - Flutterwave fees + merchant commission)) and vice versa for the other vendors.

The subaccounts are created under your account and funds collected for them would be settled into the provided settlement account based on your settlement cycle.

Split payment parameter definitions

Parameter	Required	Description
id	True (String)	This is the ID of the subaccount, you can get it from your dashboard e.g. RS_D87A9EE339AE28BFA2AE86041C6DE70E
transaction_split_ratio	False (Integer)	This is the ratio value representing the share of the amount you intend to give a subaccount. This is only needed when: 1. You are splitting between more than one subaccount. 2. You are not passing the exact amount you expect the subaccount to get.
transaction_charge_type	False (String)	This represents the type for the commission you would like to charge, if you would like to charge a flat fee pass the value as flat. If you would like to charge a percentage pass the value as percentage. When you pass this you override the type set as commission when the subaccount was created. If you want to pass the exact amount you expect a subaccount to get pass the value as flat_subaccount
transaction_charge	False (Float)	The flat or percentage value to charge as commission on the transaction. When you pass this, you override the values set as commission when the subaccount was created.

🚧

Using percentages as transaction charges

When setting up your transaction_charge_type value as a percentage, you would need to add the percentage value i.e. transaction_charge in decimal. e.g. transaction_charge: 0.09 is equal to a 9% commission on transactions.

JavaScript

<form>
  <script src="https://checkout.flutterwave.com/v3.js"></script>
  <button type="button" onClick="makePayment()">Pay Now </button>
</form>
<script>
  function makePayment() {
    FlutterwaveCheckout({
      public_key: "YOUR_PUBLIC_KEY",
      tx_ref: "hooli-tx-new-test",
      amount: 54600,
      currency: "NGN",
      payment_options: "card,ussd,barter",
      customer: {
        email: "[email protected]",
        phonenumber: "08102909304",
        name: "Yemi Desola",
      },
      subaccounts: [
        {
          id: "RS_D87A9EE339AE28BFA2AE86041C6DE70E",
          transaction_split_ratio:2,
          transaction_charge_type: "flat",
          transaction_charge: 100
        },

        {
          id: "RS_344DD49DB5D471EF565C897ECD67CD95",
          transaction_split_ratio:3,
          transaction_charge_type: "flat",
          transaction_charge: 100
        },

        {
          id: "RS_839AC07C3450A65004A0E11B83E22CA9",
          transaction_split_ratio:5,
          transaction_charge_type: "flat",
          transaction_charge: 100
        }
        
      ],
      callback: function (data) {
        console.log(data);
      },
      customizations: {
        title: "My store",
        description: "Payment for items in cart",
        logo: "https://assets.piedpiper.com/logo.png",
      },
    });
  }
</script>

From the example above, the marketplace owner would earn an N300 commission, Flutterwave would take it's configured fee then the remaining amount would be split between the 3 vendors.

Passing the exact amount you want a subaccount to receive

The default implementation for subaccounts expects that you pass the total amount value to be charged from the customer and Flutterwave calculates the amount to be sent to the subaccount based on the commission you have setup. In a case where it's more than one subaccount, we ask that you pass a split ratio which divides the funds between the subaccounts based on the ratio supplied.

For more autonomy on handling the amount you expect your marketplace merchant (subaccount) to receive, we created a flow that allows you to pass the exact amount you want your subaccount to get. We describe how it works below:

📘

Handling the exact amount your subaccounts receive

To make this possible please pass the amount you want your subaccount to get in the subaccount array as transaction_charge: "{amount}" and pass the flag that indicates you are specifying the amount you expect the subaccount to receive by adding transaction_charge_type: "flat_subaccount"

Please see a sample below.

PS: We expect that before you pass the amount to us, you have calculated the transaction processing fee and commission and it has be deducted from the amount you pass.

Multiple subaccounts

<form>
  <script src="https://checkout.flutterwave.com/v3.js"></script>
  <button type="button" onClick="makePayment()">Pay Now </button>
</form>
<script>
  function makePayment() {
    FlutterwaveCheckout({
      public_key: "YOUR_PUBLIC_KEY",
      tx_ref: "hooli-tx-new-test",
      amount: 54600,
      currency: "NGN",
      payment_options: "card,ussd,barter",
      customer: {
        email: "[email protected]",
        phonenumber: "08102909304",
        name: "Yemi Desola",
      },
      subaccounts: [
        {
          id: "RS_D87A9EE339AE28BFA2AE86041C6DE70E",
          transaction_charge_type: "flat_subaccount",
          transaction_charge: "100"
        },
              
        {
          id: "RS_344DD49DB5D471EF565C897ECD67CD95",
          transaction_charge_type: "flat_subaccount",
          transaction_charge: "100"
        },
              
        {
          id: "RS_839AC07C3450A65004A0E11B83E22CA9",
          transaction_charge_type: "flat_subaccount",
          transaction_charge: "100"
        }
        
      ],
      callback: function (data) {
        console.log(data);
      },
      customizations: {
        title: "My store",
        description: "Payment for items in cart",
        logo: "https://assets.piedpiper.com/logo.png",
      },
    });
  }
</script>

In the example above we assume you have calculated the total amount to go to each subaccount fee (processing fees and commissions). From the samples, the subaccounts would get what you passed as transaction_charge after any transaction.