DocumentationRecipesAPI ReferencesSupportBlog
Documentation

Split Payment

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

Suggest Edits

Rave's split payment feature allows you 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.

Rave 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 merchant's 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 rave dashboard and how you can collect payments on behalf of these subaccounts.

📘

Subaccount Account Numbers on Test environment

When setting up a subaccount, you would need to use test account numbers in the test environment.

Make use of account numbers within the range 0690000021 - 0690000041
Bank: 044 (Access bank).

👍

Testing Subaccount successful

To test the subaccount split successfully on the test environment, you would need to make payments with the Test bank accounts.

How to create subaccounts

On rave you can create subaccounts using two methods a.) create the subaccount on the dashboard b.) create the subaccount using our APIs.

We would show you how to use the first option below, to see how to create subaccounts via APIs visit the API documentation section.

Create a subaccount

1873 1876 1874

When you create a subaccount you would be using the subaccount ID to help the subaccount collect payments.

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

<form>
    <script src="https://api.ravepay.co/flwv3-pug/getpaidx/api/flwpbf-inline.js"></script>
    <button type="button" onClick="payWithRave()">Pay Now</button>
</form>

<script>
    const API_publicKey = "<ADD YOUR PUBLIC KEY HERE>";

    function payWithRave() {
        var x = getpaidSetup({
            PBFPubKey: API_publicKey,
            customer_email: "[email protected]",
            amount: 2000,
            currency: "NGN",
            txref: "rave-123456",
            subaccounts: [
              {
                id: "RS_D87A9EE339AE28BFA2AE86041C6DE70E",
		            transaction_split_ratio:"2"
              },
              
              {
                id: "RS_344DD49DB5D471EF565C897ECD67CD95",
                transaction_split_ratio:"3"
              },
              
              {
                id: "RS_839AC07C3450A65004A0E11B83E22CA9",
                transaction_split_ratio:"5"
              }
            ],
            meta: [{
                metaname: "flightID",
                metavalue: "AP1234"
            }],
            onclose: function() {},
            callback: function(response) {
                var txref = response.tx.txRef; // collect flwRef returned and pass to a 					server page to complete status check.
                console.log("This is the response returned after a charge", response);
                if (
                    response.tx.chargeResponseCode == "00" ||
                    response.tx.chargeResponseCode == "0"
                ) {
                    // redirect to a success page
                } else {
                    // redirect to a failure page.
                }

                x.close(); // use this to close the modal immediately after payment.
            }
        });
    }
</script>

<form>
    <script src="https://api.ravepay.co/flwv3-pug/getpaidx/api/flwpbf-inline.js"></script>
    <button type="button" onClick="payWithRave()">Pay Now</button>
</form>

<script>
    const API_publicKey = "<ADD YOUR PUBLIC KEY HERE>";

    function payWithRave() {
        var x = getpaidSetup({
            PBFPubKey: API_publicKey,
            customer_email: "[email protected]",
            amount: 2000,
            currency: "NGN",
            txref: "rave-123456",
            subaccounts: [
              {
                id: "RS_D87A9EE339AE28BFA2AE86041C6DE70E" // This assumes you have setup your commission on the dashboard.
              }
            ],
            meta: [{
                metaname: "flightID",
                metavalue: "AP1234"
            }],
            onclose: function() {},
            callback: function(response) {
                var txref = response.tx.txRef; // collect flwRef returned and pass to a 					server page to complete status check.
                console.log("This is the response returned after a charge", response);
                if (
                    response.tx.chargeResponseCode == "00" ||
                    response.tx.chargeResponseCode == "0"
                ) {
                    // redirect to a success page
                } else {
                    // redirect to a failure page.
                }

                x.close(); // use this to close the modal immediately after payment.
            }
        });
    }
</script>

The subaccounts are passed to the inline 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 - rave 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 the settlement cycle.

Split payment parameters

ParameterRequiredDescription
idTrue
(String)		This is the ID of the subaccount, you can get it from your dashboard e.g. RS_D87A9EE339AE28BFA2AE86041C6DE70E
transaction_split_ratioFalse
(String)		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_typeFalse
(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_chargeFalse
(String)		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://api.ravepay.co/flwv3-pug/getpaidx/api/flwpbf-inline.js"></script>
    <button type="button" onClick="payWithRave()">Pay Now</button>
</form>

<script>
    const API_publicKey = "<ADD YOUR PUBLIC KEY HERE>";

    function payWithRave() {
        var x = getpaidSetup({
            PBFPubKey: API_publicKey,
            customer_email: "[email protected]",
            amount: 20000,
            currency: "NGN",
            txref: "rave-123456",
            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"
              }
            ],
            meta: [{
                metaname: "flightID",
                metavalue: "AP1234"
            }],
            onclose: function() {},
            callback: function(response) {
                var txref = response.tx.txRef; // collect flwRef returned and pass to a 					server page to complete status check.
                console.log("This is the response returned after a charge", response);
                if (
                    response.tx.chargeResponseCode == "00" ||
                    response.tx.chargeResponseCode == "0"
                ) {
                    // redirect to a success page
                } else {
                    // redirect to a failure page.
                }

                x.close(); // use this to close the modal immediately after payment.
            }
        });
    }
</script>

From the example above, the marketplace owner would earn an N300 commission, rave 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 rave 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 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://api.ravepay.co/flwv3-pug/getpaidx/api/flwpbf-inline.js"></script>
    <button type="button" onClick="payWithRave()">Pay Now</button>
</form>

<script>
    const API_publicKey = "<ADD YOUR PUBLIC KEY HERE>";

    function payWithRave() {
        var x = getpaidSetup({
            PBFPubKey: API_publicKey,
            customer_email: "[email protected]",
            amount: 20000,
            currency: "NGN",
            txref: "rave-123456",
            subaccounts: [
              {
                id: "RS_D87A9EE339AE28BFA2AE86041C6DE70E",
                transaction_charge_type: "flat_subaccount",
                transaction_charge: "1000"
              },
              
              {
                id: "RS_344DD49DB5D471EF565C897ECD67CD95",
                transaction_charge_type: "flat_subaccount",
                transaction_charge: "100"
              },
              
              {
                id: "RS_839AC07C3450A65004A0E11B83E22CA9",
                transaction_charge_type: "flat_subaccount",
                transaction_charge: "400"
              }
            ],
            meta: [{
                metaname: "flightID",
                metavalue: "AP1234"
            }],
            onclose: function() {},
            callback: function(response) {
                var txref = response.tx.txRef; // collect flwRef returned and pass to a 					server page to complete status check.
                console.log("This is the response returned after a charge", response);
                if (
                    response.tx.chargeResponseCode == "00" ||
                    response.tx.chargeResponseCode == "0"
                ) {
                    // redirect to a success page
                } else {
                    // redirect to a failure page.
                }

                x.close(); // use this to close the modal immediately after payment.
            }
        });
    }
</script>

<form>
    <script src="https://api.ravepay.co/flwv3-pug/getpaidx/api/flwpbf-inline.js"></script>
    <button type="button" onClick="payWithRave()">Pay Now</button>
</form>

<script>
    const API_publicKey = "<ADD YOUR PUBLIC KEY HERE>";

    function payWithRave() {
        var x = getpaidSetup({
            PBFPubKey: API_publicKey,
            customer_email: "[email protected]",
            amount: 2000,
            currency: "NGN",
            txref: "rave-123456",
            subaccounts: [
              {
                id: "RS_D87A9EE339AE28BFA2AE86041C6DE70E", // This assumes you have setup your commission on the dashboard.
                transaction_charge: 1980,
                transaction_charge_type: "flat_subaccount"
              }
            ],
            meta: [{
                metaname: "flightID",
                metavalue: "AP1234"
            }],
            onclose: function() {},
            callback: function(response) {
                var txref = response.tx.txRef; // collect flwRef returned and pass to a 					server page to complete status check.
                console.log("This is the response returned after a charge", response);
                if (
                    response.tx.chargeResponseCode == "00" ||
                    response.tx.chargeResponseCode == "0"
                ) {
                    // redirect to a success page
                } else {
                    // redirect to a failure page.
                }

                x.close(); // use this to close the modal immediately after payment.
            }
        });
    }
</script>

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

Updated almost 6 years ago