Split payments at authorization

Learn how to split a Terminal API payment at the time of authorization.

Split configuration profiles

Besides splitting payments at the transaction level, you can also set up profiles to automatically direct fees and book funds to predefined balance accounts.

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.

This page describes how to provide split instructions in individual Terminal API payment requests.

Requirements

In addition to the general requirements for in-person payments with an Adyen for Platforms integration, take into account the following information.

Requirement	Description
Integration type	A Terminal API integration with payment terminals or with a Mobile solution. The standalone solution does not support adding split instructions to individual payment authorization requests.

How it works

To provide the split instructions in your payment request, you must:

Gather the split instructions you need to send in the request.
The split instructions consist of general information such as the number of splits that the transaction will be divided into, and the details of every split such as the type of split and the account to book the split amount to.
Format the split instructions.
The split instructions must be provided as a single string value. To achieve that, you can create a JSON object and Base64 encode that, or you can concatenate key-value pairs.
Make the payment request, specifying the string with the split instructions.
Track the result.
The Terminal API does not validate the balance accounts specified in the split instructions. Using transfer and transaction webhooks, you can check if the funds were booked as intended

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

USD 75.00 is booked to your user's balance account as payment for the goods or services.
USD 5.00 is booked to your liable balance account as your platform's commission.
All transaction fees are booked to your user's balance account.

1. Gather the split instructions

The split instructions that you need to provide in your payment request consist of:

General information about the currency and total amount of the transaction, and the number of splits that the transaction will be divided into.
The details of every split, such as the type of split and the account to book the split amount to.
Every split is called a split item, and is indicated with a number, starting at 1. The details of the first split are preceded by split.item1, the details of the second split are preceded by split.item2, and so on.

Gather the following general split information:

Field	Required	Description
`split.api`		The version of the Split API: 1.
`split.totalAmount`		The transaction mount in minor units. Must be equal to the sum of the split amounts.
`split.currencyCode`		The currency of the transaction.
`split.nrOfItems`		The number of splits you want to create. Must match the sum of split items in the request.

For every split item, gather the following details:

Field	Required	Description
`split.item[ITEM_NUMBER].amount`		The amount of the split item, in minor units. Do not include this field when splitting fees, tips, or surcharges, because those amounts are not known at the time of payment.
`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 to the specified balance account. Commission: Books the commission to your liable balance account. Tip: Books the tip to the specified balance account. Surcharge: Books the surcharge to the specified balance account. We recommend that you also include at least one transaction fee type in your request, for example, PaymentFee. All undefined transaction fees are booked to your platform's liable balance account.
`split.item[ITEM_NUMBER].account`		The 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. Do not include this field when the `split.item[ITEM_NUMBER].type` is Commission.
`split.item[ITEM_NUMBER].reference`		The reference for that specific transaction split, which is returned in our reporting. We strongly recommend that you always include a reference for the split item. Required when the `split.item[ITEM_NUMBER].type` is BalanceAccount.
`split.item[ITEM_NUMBER].description`		The description of that specific transaction split, which is returned in our reporting.

The following example shows the split instructions for a payment that will be divided into three split items. For two of the three split items an amount is known, and the sum of these two split amounts is the same as the total transaction amount.

Now that you have gathered the split instructions, the next step is to format them so that you can pass them in the SaleToAcquirerData field of the payment request.

2. Format the split instructions

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

Option 1: as a string of form-encoded key-value pairs (using & as a separator).
Option 2: as a JSON object converted to a Base64-encoded string.

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

Select the tab for the option you want to use.

3. Make a payment request

Make a Terminal API payment request, specifying:

The standard SaleToPOIRequest.MessageHeader object, with MessageClass set to Service and MessageCategory set to Payment.

Parameter	Required	Description
`ProtocolVersion`		3.0
`MessageClass`		Service
`MessageCategory`		Payment
`MessageType`		Request
`ServiceID`		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`		Your unique ID for the POS system component to send this request from.
`POIID`		The unique ID of the terminal to send this request to. Format: [device model]-[serial number].

The PaymentRequest object with:

Parameter	Required	Description
`SaleData.SaleTransactionID`		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`: The date and time of the request in UTC format.
`SaleData.SaleToAcquirerData`		The split payment instructions you gathered, provided as a string of concatenated key-value pairs or as a JSON object converted to a Base64-encoded string. See Format the data.
`PaymentTransaction.AmountsReq`		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 USD 10, enter 10.00 (not 1000).

The following example shows a payment request for USD 80.00 with the split instructions formatted as concatenated key-value pairs. The payment is split three ways:

USD 75.00 is booked to your user's balance account as payment for the goods or services.
USD 5.00 is booked to your liable balance account as your platform's commission.
All transaction fees are booked to your user's balance account.

The payment request is routed to the terminal or mobile device, for the customer to complete the payment. The payment is approved, and then sent to the Adyen payments platform for processing.

When you receive the PaymentResponse, check the following parameters:
- POIData.POITransactionID.TransactionID: The transaction identifier for the payment consisting of the tender reference followed by the PSP reference. For example, in the transaction identifier BV0q001765198054002.CWBC43ZX2VTFWR82, the PSP reference is CWBC43ZX2VTFWR82.
- Response.Result: Success
- Response.AdditionalResponse: The additional transaction data. Its format corresponds to the format of the SaleToAcquirerData in the payment request: form-encoded key-value pairs, or a Base64-encoded JSON object.
- PaymentReceipt: The object with data you can use to generate a receipt.
```
{
 "SaleToPOIResponse": {
   "MessageHeader": {...},
   "PaymentResponse": {
     "POIData": {
       "POITransactionID": {
         "TimeStamp": "...",
         "TransactionID":"BV0q001765198054002.CWBC43ZX2VTFWR82"
       }
     },
     "PaymentReceipt": [...],
     "PaymentResult": {...},
     "Response": {
       "AdditionalResponse": "...posAuthAmountCurrency=USD&posAuthAmountValue=8000&...pspReference=CWBC43ZX2VTFWR82...",
       "Result": "Success",
     },
     "SaleData": {...}
   }
 }
}
```
You can also view this information in your Customer Area:
- To view the details of the payment, go to Transactions > Payments
- To view the breakdown of the splits, go to Platforms > Transfers.

4. Track fund movements

The API request validates only the format of the split instructions, not the balance accounts specified in the request. This means that even if the transaction 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 and its fees are booked to your platform's liable balance account.

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

To track the status of the funds transfers initiated by a payment:

Listen to the following webhooks:
- Transfer webhooks: Adyen sends a balancePlatform.transfer.created webhook to inform your server that funds will be credited to balance accounts, and balancePlatform.transfer.updated webhooks after every status change.
- Transaction webhooks: Adyen sends a balancePlatform.transaction.created webhook to inform your server that funds have been credited to a balance account.
Acknowledge the webhooks. We send these webhooks for every split item in the payment.
In the payload of the balancePlatform.transfer.updated webhook, note that:
- The event array includes all previous transfer events.
- The sequenceNumber defines the number of webhooks sent for the transfer, including the current one.

Examples

Your server receives webhooks for each split of the payment amount. The following examples are based on a standard split payment use case.

Additional split instructions

In addition to the standard use cases, you can also book the following split types to your user's balance account:

Transaction fees
Chargebacks
Surcharges
Top-ups

Different types of transaction fees

The split type PaymentFee books the total amount of all your transaction fees to the specified balance account. However, you can also choose to split the total transaction fee amount, and book different kinds of fees to different balance accounts.

For more information about the transaction fee types, and how to book them to different balance accounts, see Transaction fees.

Surcharges

When your users pass on the costs of accepting payments to their customers, this is called a surcharge. You can use split instructions to define how to book the surcharge within your platform.

For more information, see Surcharge.

Tips

When your user receives a tip from their customer, you can book this tip directly to their balance account.

For more information, see Tipping.

Best practices

We strongly recommend sending a reference for each split. 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 instructions at capture instead. Split instructions provided at capture overrides any split instructions provided with the initial payment request. However, we recommend that you provide the split instructions 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 instructions are provided in the payment request.