Split data in additionalData

This page describes providing split instructions in additionalData. This has been replaced with providing split instructions as a root element starting with API version 37.

For information about platform integrations built after August 1, 2022, refer to our new integration guide instead.

Learn how to provide split instructions in the additionalData object.

Providing split instructions

Split instructions define how a payment is split. You can split the payment amount into any number of accounts.

Provide split instructions in the additionalData object. This object is present in all payment requests for any payment integration (e.g. /authorise and /payments endpoints).

Split data can also be provided when submitting a capture or refund request.

Split API uses dot notation with key-value pairs to provide information.

For each request, you will need to specify the split.api as 1, the amount of the transaction total in split.totalAmount, and the currency in split.currencyCode:

...
"additionalData": {
   "split.api":1,
   "split.totalAmount":40000,
   "split.currencyCode":"USD",
   ...
}

Provide the number of times you will split the payment in split.nrOfItems. Specify each split as an item followed by an incrementing number starting at 1: split.item1, split.item2, and so on.

Each split item will also need to include:

The amount to be split.
The split type. A type of MarketPlace sends the amount to the account specified. A split type of Commission sends the split to your liable account.
The account to send the split. This is the accountCode of one of your account holder's accounts or your own liable account.
An optional reference, this is returned in our reporting for that specific transaction split.

Transactions are split into accounts and not account holders.

Here is an example for splitting a USD 400.00 transaction:

300.00 is being split into an account with accountCode of 163298747.
100.00 being split into the platform's liable account.

 {
   ...
   "additionalData":{
      "split.api":"1",
      "split.nrOfItems":"2",
      "split.totalAmount":40000,
      "split.currencyCode":"USD",
      "split.item1.amount":30000,
      "split.item1.type":"MarketPlace",
      "split.item1.account":"163298747",
      "split.item1.reference":"QXhlbFN0b2x0ZW5iZXJnCg",
      "split.item2.amount":10000,
      "split.item2.type":"Commission",
      "split.item2.reference":"THVjYXNCbGVkc29lCg"
   },
   ...
}

Split payment with /authorise

Here is an example of split instructions provided with /authorise call.

{
   "card":{
      "number":"4400 0000 0000 0008",
      "cvc":"737",
      "expiryMonth":"03",
      "expiryYear":"2030",
      "holderName":"John Smith"
   },
   "amount":{
      "value":40000,
      "currency":"USD"
   },
   "reference":"YOUR_REFERENCE_NUMBER",
   "merchantAccount":"YOUR_MERCHANT_ACCOUNT",
   "additionalData":{
      "split.api":"1",
      "split.nrOfItems":"2",
      "split.totalAmount":"40000",
      "split.currencyCode":"USD",
      "split.item1.amount":"30000",
      "split.item1.type":"MarketPlace",
      "split.item1.account":"163298747",
      "split.item1.reference":"QXhlbFN0b2x0ZW5iZXJnCg",
      "split.item2.amount":"10000",
      "split.item2.type":"Commission",
      "split.item2.reference":"THVjYXNCbGVkc29lCg"
   }
}