Marketpay icon

Split at payment

Learn how to split a transaction at the time of payment.

When accepting in-person payments, you can split the payment amount between the balance accounts in your platform. This allows you to book the sale amount, tip, surcharge, transaction fees, and your platform's commission separately.

To provide this split information in your payment request, you must:

  1. Gather and prepare the data you need to send in the request.
  2. Make the payment request.
  3. Check the payment result.

The examples on this page are based on a split payment request for EUR 620.00, split three ways:

  • EUR 600.00 is booked to your user's balance account as payment for the goods or services.
  • EUR 20.00 is booked to your liable balance account as your platform's commission.
  • All transaction fees are booked to your user's balance account.

Step 1: Gather the data

Gather the following data that you need pass inside SaleToAcquirerData of the payment request:

Field Description Example
split.api Version of the Split API: 1. split.api=1
split.totalAmount The full transaction mount, in minor units.
Must be equal to the sum of the split amounts.
split.totalAmount=62000
split.currencyCode Currency of the transaction. split.currencyCode=EUR
split.nrOfItems The number of splits you want to create.
Must match the sum of split items in the request.
split.nrOfItems=3

Every split of the full amount is called a split item, and needs to be specified with a different number, starting at 1.
For every split item, like split.item1, split.item2, and so on, include the following:

Field Description Example
split.item[ITEM_NUMBER].amount Amount of each split item, in minor units. You do not need to specify the amount for the fees, since this is not known at the time of payment. split.item1.amount=60000
split.item2.amount=2000
split.item[ITEM_NUMBER].type Defines the part of the payment you want to book to the specified split.item[ITEM_NUMBER].account.
Possible values:
  • BalanceAccount: books the sale amount against the specified balance account.
  • Commission: books the commission against your liable balance account.
  • Remainder: books the amount left over after a currency conversion to the specified balance account.
  • Tip: books the tip to the specified balance account.
  • Surcharge: books the surcharge to the specified balance account.
  • You can also book different types of transaction fees to different balance accounts.
split.item1.type=BalanceAccount
split.item2.type=Commission
split.item3.type=PaymentFee
split.item[ITEM_NUMBER].account Account that will receive (or be charged) the split. This is the balanceAccountID of one of your user's balance accounts or your own liable account. You don't need to specify this field when the split.item[ITEM_NUMBER].type is Commission. split.item1.account=BA00000000000000000000001
split.item3.account=BA00000000000000000000001
split.item[ITEM_NUMBER].reference The reference for that specific transaction split, which is returned in our reporting. Required if the split.item[ITEM_NUMBER].type is BalanceAccount. split.item1.reference=reference_split_1
split.item2.reference=reference_commission
split.item3.reference=reference_PaymentFee
split.item[ITEM_NUMBER].description The description for that specific transaction split, which is returned in our reporting. split.item1.description=description_split_1
split.item2.description=description_commission
split.item3.description=description_PaymentFee

Step 2: Prepare the data

There are two ways to pass data elements in the SaleToAcquirerData field of your request:

  • Option 1: as form-encoded key-value pairs (using & as a separator).
  • Option 2: as a JSON object converted to a Base64-encoded string.
  1. Concatenate the key-pairs from Step 1 into a string by separating them with ampersands (&).

  2. Pass this string in the SaleToAcquirerData object of your request.

The format you choose in your request is the format that will be returned in the AdditionalResponse. To always receive the AdditionalResponse in the same format, contact our Support Team

Step 3: Make a payment request

Make a POST request to a Terminal API endpoint, specifying:

MessageHeader

MessageHeader is the standard SaleToPOIRequest.MessageHeader object, and includes the following parameters:

Parameter Required Description
ProtocolVersion -white_check_mark- 3.0
MessageClass -white_check_mark- Service
MessageCategory -white_check_mark- Payment
MessageType -white_check_mark- Request
ServiceID -white_check_mark- Your unique ID for this request, consisting of 1-10 alphanumeric characters. Must be unique within the last 48 hours for the terminal (POIID) being used.
SaleID -white_check_mark- Your unique ID for the POS system component to send this request from.
POIID -white_check_mark- The unique ID of the terminal to send this request to. Format: [device model]-[serial number].

PaymentRequest

PaymentRequest is the request body, which includes:

Parameter Required Description
SaleData.SaleTransactionID -white_check_mark- An object with:
  • TransactionID: your reference to identify a payment. We recommend using a unique value per payment. In your Customer Area and Adyen reports, this will show as the merchant reference for the transaction.
  • TimeStamp: date and time of the request in UTC format.
SaleData.SaleToAcquirerData -white_check_mark- Provides the split payment data as concatenated key-value pairs separated by an ampersand (&) character, or in Base64-encoded format. See steps 1 and 2 for instructions.
PaymentTransaction.AmountsReq -white_check_mark- An object with:
  • Currency: the transaction currency.
  • RequestedAmount: the transaction amount.
    Specify the amount with a decimal point. Do not use minor units. For example, for an amount of EUR 10, enter 10.00 (not 1000).

The following example shows a payment request for EUR 620.00, split three ways:

  1. EUR 600.00 is booked to your user's balance account as payment for the goods or services.
  2. EUR 20.00 is booked to your liable balance account as your platform's commission.
  3. All transaction fees are booked to your user's balance account.

The payment request is routed to the terminal, for the customer to present their card and verify the payment. The payment is then sent to the Adyen payments platform for processing.

Step 4: Check the payment result

If your integration uses asynchronous cloud communications, you must set up event notifications. We then send the Terminal API responses to your endpoint.

If the payment is successful:

  • Approved is shown on the terminal display.
  • You receive a payment response with:
    • POIData.POITransactionID.TransactionID: transaction identifier for the payment in the format tenderReference.pspReference. For example, oLkO0012498220087000.981517998282382C.
    • PaymentResponse.Response.Result: Success
    • PaymentResponse.Response.AdditionalResponse: additional transaction data. Its format corresponds to the format of the SaleToAcquirerData in the payment request: a Base64-encoded JSON object or form-encoded key-value pairs.
    • PaymentReceipt: object with data you can use to generate a receipt.
{
  "SaleToPOIResponse":{
    "MessageHeader":{...},
    "PaymentResponse":{
      "POIData":{
        "POITransactionID":{
          "TransactionID": "oLkO0012498220087000.981517998282382C"
        },
        ...
      },
      "Response":{
        "AdditionalResponse":"split.api=1&split.nrOfItems=4&split.totalAmount=62000&split.currencyCode=EUR&split.item1.amount=60000&split.item1.type=BalanceAccount&split.item1.account=BA00000000000000000000001&split.item1.reference=reference_split_1&split.item1.description=description_split_1&split.item2.amount=2000&split.item2.type=Commission&split.item2.reference=reference_commission&split.item2.description=description_commission&split.item3.type=PaymentFee&split.item3.account=BA00000000000000000000001&split.item3.reference=reference_PaymentFee&split.item3.description=description_PaymentFee",
        "Result":"Success",
      },
      ...
    },
    "PaymentReceipt":{...}
  }
}

You can also view the details of a payment in your Customer Area under Transactions > Payments, and the breakdown of the splits in your Balance Platform Customer Area.

Best practice

We strongly recommend sending a reference for all split types. You can use the reference to reconcile the split amounts in the transaction overview and in the reports. Without a reference, the split amounts are aggregated in a single entry and you will be unable to reconcile the transactions.

If you do not know the split amounts at the time of payment, you can provide split data at capture instead. Split data provided at capture overrides any split data provided with the initial payment request. However, we recommend that you provide the split information at the time of payment, rather than at capture. Because some payment methods do not support delayed captures, the funds may not be booked correctly unless the split data is provided in the payment request.

The API request validates only the format of the split data, not the balance accounts specified in the request. This means that even if the payment, capture, and refund is successful, it is possible that the funds are not credited to/deducted from the specified balance account. If the balance account does not exist, or it is linked to an account holder with a closed status, the full transaction (sale amount, commission, and fees) is booked to your platform's liable balance account.

To correct the balances, you can transfer the funds between the balance accounts in your platform.

See also