The Flutterwave Developer Documentation

We have put together comprehensive guidelines and documentation to help you get right into integrating any of our products quickly. You can also get support when you need help!

API Documentation    API Reference

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.

<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>
<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.

<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.

<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.

Updated 3 months ago


Split Payment


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

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.