Are you looking for test card numbers?

Would you like to contact support?

Marketpay icon

Split data in additionalData

This page describes providing split data in additionalData. This has been replaced with providing split data 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 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 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 1split.item1split.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 400.00 USD 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"
   }
}