Are you looking for test card numbers?

Would you like to contact support?

No momento, esta página não está disponível em português
Marketpay icon

Split a payment

Split a payment between the balance accounts in your platform.

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

To split a payment, you can provide split information at the time of payment or at the time of capture. If you do not provide split information in your payment or capture request, the full amount is booked to your liable account.

We recommend that you always provide split information at the time of payment, rather than at capture. Since certain payment methods do not support delayed captures, the funds may not be booked correctly unless split data is provided in the payment request.

You can provide split information at the time of payment.

For example, a payment of EUR 620.00 is split into:

  • EUR 600.00 to be paid to your user's balance account.
  • EUR 20.00 to be paid to your liable account as your platform's commission.

To provide this split information in your payment request:

Step 1: Gather the data

  1. Gather the data that you will pass inside SaleToAcquirerData of the payment request:

    • Specify the following:

      Field Description Example
      split.api Version of the Split API: 1. split.api=1
      split.totalAmount Amount to be split, in minor units. Must be equal to the transaction amount which is the sum of the split amounts. split.totalAmount=62000
      split.currencyCode Currency of the amount you intend to split. split.currencyCode=EUR
      split.nrOfItems Number of times you split the payment. Must match the number 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.item[ITEM_NUMBER].type Split type.
      • BalanceAccount: books the sale amount against the specified balance account.
      • PaymentFee: books the transaction fees to the specified balance account.
      • Commission: books the commission against your liable account.
      • Tip: books the tip to the specified balance account.
      • Surcharge: books the surcharge to the specified balance account.
      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.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.item[ITEM_NUMBER].description The description for that specific transaction split, which is returned in our reporting. split.item1.description=description_split_1
      The data for the split payment

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 POS Support Team

Step 3: Make a payment request

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

  • MessageHeader: the standard SaleToPOIRequest.MessageHeader object. This includes:

    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: The request body. This 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 10 EUR specify 10.00 (not 1000).

Here is an example terminal API request to split a payment of EUR 620.00 using key-value pairs:

Payment request with split data
    "SaleToPOIRequest": {
        "MessageHeader": {
            "ProtocolVersion": "3.0",
            "MessageClass": "Service",
            "MessageCategory": "Payment",
            "MessageType": "Request",
            "SaleID": "POSSystemID12345",
            "ServiceID": "0207111104",
            "POIID": "V400m-324688179"
        "PaymentRequest": {
            "SaleData": {
                "SaleTransactionID": {
                    "TransactionID": "27908",
                    "TimeStamp": "2022-10-28T10:11:04+00:00"
                "SaleToAcquirerData": "split.api=1&split.nrOfItems=3&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"
            "PaymentTransaction": {
                "AmountsReq": {
                    "Currency": "EUR",
                    "RequestedAmount": 620.00

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.

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

See also