Split payments serve as the instruction towards Rootline to route the balance of an incoming payment to the designated account or accounts.

The Payment API handles splits as an addition to the payment request. In an array, you will have the possibility to instruct Rootline how the payment should be divided.

How it works

Each split that you define will become a payment in the system. We follow a recursive process whereby each split inherits the same steps of a payment as the original payment. This way, a payment, a split payment and their corresponding payment information can be shared, shown and reported on in a similar fashion to the users in your ecosystem.

The API structure

The Payment API contains a list of splits. This list can hold an indefinite amount of splits (so long the total payment amount allows it).

A split contains, amongst others, an account identifier and an amount. Each split should be seen as an instruction to transfer the specified amount to the selected account.

Example split payment

{
    "account_id": "{{account_id}}",  // your partner account with Rootline
    "amount": {
        "currency": "EUR",
        "quantity": "20.00"
    },
    "splits": [
        {
            "account_id": "{{account_id}}", // your client's account
            "amount": {
                "quantity": "15.00",
                "currency": "EUR"
            },
            "reference": "394f4ac2-060b-4e54-a982-b473bafc0e3b",
            "description": "Payment for Project X"
        },
        {
            "account_id": "{{account_id}}", // another client's account
            "amount": {
                "quantity": "5.00",
                "currency": "EUR"
            },
            "reference": "0d2d48f8-059a-4a21-ac89-a7c0bb0b538f",
            "description": "Payment for Project Y"
        }
    ],
    "reference": "ef5bc3e2-dfc9-491c-89ac-c143dd34f3d0",
    "description": "Your test description",
    "statement_descriptor": "Invoice 20240412",
    "return_url": "https://your-url.com/"
}

In this example, the top level account_id will be the identifier of your partner account, the main account that you have with us. The account_id's in the splits will be the identifiers of the accounts that you want the balance to end up in.

Your response for the submitted payment will look like the below.

{
    "account_id": "{{account_id}}",
    "id":"pmt_4ClciVXj203rqAxohzs6Cq",
    "object":"payment",
    "created_at": "2024-05-29T14:23:15.733669Z",
    "amount": {
        "currency": "EUR",
        "quantity": "20.00"
    },
    "splits": [
        {
            "account_id": "{{account_id}}",
            "id":"pmt_V8QvGEFbTeyI7CWUEA6jc",
            "amount": {
                "quantity": "15.00",
                "currency": "EUR"
            },
            "reference": "394f4ac2-060b-4e54-a982-b473bafc0e3b",
            "description": "Payment for Project X"
        },
        {
            "account_id": "{{account_id}}",
            "id":"pmt_5T24Zxy18WUdnyQTK8WSsm",
            "amount": {
                "quantity": "5.00",
                "currency": "EUR"
            },
            "reference": "0d2d48f8-059a-4a21-ac89-a7c0bb0b538f",
            "description": "Payment for Project Y"
        }
    ],
    "reference": "ef5bc3e2-dfc9-491c-89ac-c143dd34f3d0",
    "description": "Your test description",
    "statement_descriptor": "Invoice 20240412",
    "return_url": "https://your-url.com/"
}

How to take your revenue from payments

For each payment that you process for a client, you can take a fee. You simply extend the split payment object with a (list of) fees. We currently support a flat_rate to be taken from a split payment. Imagine, you are charging a flat payment fee of € 0.30 for each transaction. The earlier example will now look as follows:

{
    "account_id": "{{account_id}}",
    "amount": {
        "currency": "EUR",
        "quantity": "20.00"
    },
    "splits": [
        {
            "account_id": "{{account_id}}",
            "amount": {
                "quantity": "15.00",
                "currency": "EUR"
            },
            "fees": [
                {
                    "flat_rate": {
                        "amount": {
                            "quantity": "0.30",
                            "currency": "EUR"
                        }
                    }
                }
            ],
            "reference": "394f4ac2-060b-4e54-a982-b473bafc0e3b",
            "description": "Payment for Project X"
        },
        {
            "account_id": "{{account_id}}",
            "amount": {
                "quantity": "5.00",
                "currency": "EUR"
            },
            "fees": [
                {
                    "flat_rate": {
                        "amount": {
                            "quantity": "0.30",
                            "currency": "EUR"
                        }
                    }
                }
            ],
            "reference": "0d2d48f8-059a-4a21-ac89-a7c0bb0b538f",
            "description": "Payment for Project Y"
        }
    ],
    "reference": "ef5bc3e2-dfc9-491c-89ac-c143dd34f3d0",
    "description": "Your test description",
    "statement_descriptor": "Invoice 20240412",
    "return_url": "https://your-url.com/"
}

What will be net credited to the designated accounts is the gross amount specified - the fees. The client that is fulfilling the service "Project X" will receive € 14.70, and the client fulfilling "Project Y" receives € 4.70 in their balance account.

Please note that -in case the payment amount is higher than the sum of the splits- the remainder will be recognized as revenue, and will be sent to your partner account. The sum of the splits cannot be higher than the top-level payment amount.

Processing account

Depending on your platform setup you may be required to provide the id for the processing account (processing_account_id). This is the case when customers interact directly with the sellers on your platform when they have questions about payments. If you are in doubt, please reach out to your contact at Rootline.

Webhooks

If you configure webhooks as described under Webhooks, you will receive them for each (split) payment that is created.