No currency is assumed in this article
Welcome to yet another article on Rave. From the title, we already know what we’re here for 😃.
Rave’s split payment feature allows you to split a transaction between two (2) or more accounts and collect your appropriate fees on the transaction. A typical scenario is when you are building a ride-hailing app and you intend to pay your drivers immediately a ride ends while you still collect your 10% or 15% share.
This article will show how to make use of Rave’s APIs to handle split payments in your applications.
NOTE: When using this feature you as the app owner is responsible for vetting the merchant’s signed up under your marketplace, this means that disputes and chargebacks would be logged against the marketplace owner.
In order to split payment between you and another person or other people, you would need to add them as subaccounts under your own rave account. If you are using our payment modal, see this article on how to create subaccounts. However, if you are calling our APIs, visit this link to read on how to create subaccounts.
Having created all the necessary subaccounts, you can now begin splitting payments between yourself and the subaccounts. BUT HOW? Well, several scenarios are shown below with code snippets.
SCENARIO 1 — You and a single subaccount (using the default setting on your dashboard — Percentage)
Let’s assume you have an online store where other merchants come to sell, and for every single sale per merchant, you have a commission of whatever amount you set on the dashboard while creating the subaccount. Let’s also assume that only one item can be bought at a time from your online store. From the figure below, whenever Jake stores makes any sale via your online store, 10% of the amount will get settled to your rave account while 90% gets settled to his bank account.
The payload for this scenario is shown below:
Apparently, the most notable part of the payload is the subaccountsparameter. As you can see, all we did is just pass the id of the subaccount and that’s it. Rave would simply pick up the id and use the default setting you set up while creating the subaccount.
SCENARIO 2 — You and a single subaccount (using the default setting on your dashboard — Flat Amount)
Same as scenario one. Only that the default setting on your dashboard is to take a flat fee for every saleJake stores makes via your store. (See image below)
The payload for this scenario is exactly the same as scenario 1 (Just copy and paste). Rave recognizes that what you set up on your dashboard is a flat fee and it would apply that appropriately.
SCENARIO 3 — You and a single subaccount (overriding the default setting on your dashboard — Percentage)
This also mimics the same scenario as that of scenario 1. The difference here is that you do not want to use the default subaccount setting you have on your dashboard. From the figure below, you have set a percentage of 10% for you and 90% for the subaccount; but for some reason, you do not want to go on with that. You’d rather take a 20% commission and give 80% to the subaccount.
No cause for alarm ⏰. All you need do is:
- update the subaccount settings via your dashboard as shown in the image below
SCENARIO 4 — You and a single subaccount (overriding the default setting on your dashboard — Flat)
Just like scenario 3, you probably have already created a subaccount with a particular split type (either percentage or flat). But for some reason, you want to override this setting. You feel that you should collect a flat fee of #500 for every sale made on your platform as opposed to what you have set on your dashboard (example below).
To do this, you have two (2) options:
- Update the subaccount setting on your dashboard (as shown in the image below) and then proceed as in scenario 2.
2. Pass two specific parameters alongside the subaccount id to the payload
- transaction_charge_type: this should have the value
flat_subaccount - transaction_charge: this should hold the exact amount you want the subaccount to have
The sample payload for this scenario is shown below.
SCENARIO 5 — You and multiple subaccounts
Let’s assume you have an online store where other merchants sell stuff, and for every single sale per merchant, you have a commission of whatever amount you set on the dashboard while creating the subaccount. Unlike the previous scenarios, there’s no limit to the number of items that can be bought at a time. i.e a customer can pick different items from different merchants and pay for all of them at once (Imagine paying for three(3) or four(4) items at checkout on Jumia).
CASE 1: using the default setting on your dashboard
This case is only applicable if you want the subaccounts you are splitting between to get the exact same amount. If this doesn’t suit you, just scroll to the next case below.
When you decide to go ahead with the default setting while splitting between multiple subaccounts, the behaviour you get is slightly different from when you are splitting with just one subaccount.
Your commission is a sum of each commission (as set on your dashboard) per merchant. So if a sale worth #10000(after transaction fees have been taken by rave) is made on your platform involving three (3) merchants with whom you have the following commission:
- merchant 1 (John Stores) — #500 flat per item bought
- merchant 2 (Tolu’s couture)– 10% per item bought
- merchant 3 (Abeni clothing)–10% per item bought
Your total commission for that #10000 sale will be:
(500) + (10% * 10000) + (10% * 10000) = #2500
It is after your commission has been calculated that the leftover (10000–2500 = 7500) will then be split among the subaccounts:
Subaccounts value = leftover / total number of subaccounts
In our case, 7500 / 3 = 2500. Hence, each subaccount gets exactly #2500.
Now that you understand how this works (well hopefully), here’s a sample payload that achieves exactly this:
CASE 2: Passing the exact amount your subaccounts should get
This use case assumes that you have already done your calculations and have determined how much each of your subaccounts should get once a transaction is made.
Using the same example as in case 1(same commissions apply). Now we are concerned with the actual cost of each of the items
- A water bottle — sold by John Stores. Price: #1800
- A Knapsack — sold by Tolu’s Couture. Price: #2200
- A hoodie — sold by Abeni Clothing. Price: #6000
Time for some calculations 😃 to determine how much exactly each subaccount should get.
subaccount value = item price — commission
NB: It’s your job to determine your commissions
John Stores: 1800–500 = 1300
Tolu’s Couture: 2200 — (10% * 2200) = 2200–220 = 1980
Abeni’s Couture: 6000 — (10% of 6000) = 6000–600 = 5400
Now that you have the exact amount for each of the subaccounts, all you need to is to pass two specific parameters alongside the subaccount id to the payload:
- transaction_charge_type: this should have the value
flat_subaccount - transaction_charge: this should hold the exact amount you want the subaccount to have
Sample payload for this case is shown below:
CASE 3: Using a split ratio to determine how much each subaccount gets
Sometimes you may want to use a ratio to determine how much each of your subaccounts gets. This is also useful if you do not want each subaccount to get the same amount when the split is carried out.
Any number between 0 and 10 would suffice as a valid ratio to be passed on to Rave. A ratio of 1 represents 10%, 2–20%, 3–30% … 9–90%, 10 – 100%
Before any ratio you set is applied, Rave would first calculate your own commission based on whatever you have set on your dashboard. Using case 1example, if a sale worth #10000(after transaction fees have been taken by rave) is made on your platform involving three (3) merchants with whom you have the following commission:
- merchant 1 (John Stores) — #500 flat per item bought
- merchant 2 (Tolu’s couture)– 10% per item bought
- merchant 3 (Abeni clothing)–10% per item bought
Your total commission for that #10000 sale will be:
(500) + (10% * 10000) + (10% * 10000) = #2500
After your commission has been calculated, Rave would the apply whatever ratio you have set on the leftover amount — in this case, #7500.
Let’s assume that we set the following ratio: John Stores: 2 Tolu’s Couture: 5Abeni’s Couture: 3. They would each get
John Stores: 20% * 7500 = #1500
Tolu’s Couture: 50% * 7500 = #3750
Abeni’s Couture: 30% * 7500 = #2250.
Now that you understand how this works (well hopefully), here’s a sample payload that achieves exactly this:
NOTE
Rave’s mobile SDKs make it easy to implement any of these split payment cases and scenarios. Check them out — Android SDK, IOS SDK, Ionic SDK,React Native.
WOW! 😁 you’ve made it thus far. I hope you would be able to implement Rave split payments without any hassle.
If you enjoyed this article, please don’t forget to gimme a 👏. Also, if you have any comments, use the comment section below.
Gracias.