Split data in additionalData

Learn how to provide split data in the additionalData object.

Providing split data

Split data defines how a payment is split. You can split a payment into any number of accounts.

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

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.

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 data provided with /authorise call.

{
   "card":{
      "number":"4400 0000 0000 0008",
      "cvc":"737",
      "expiryMonth":"10",
      "expiryYear":"2020",
      "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"
   }
}