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: Prepare the split data
You must include the following information in the request:
| Key | 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 |
Specify each split as a split.item{item#} starting at 1: split.item1, split.item2, and so on. In each split item, include:
| Key | Description | Example |
|---|---|---|
split.item{item#}.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#}.type |
Split type.
|
split.item1.type=BalanceAccount split.item2.type=Commission split.item3.type=PaymentFee |
split.item{item#}.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#}.type is Commission. |
split.item1.account=BA00000000000000000000001 split.item3.account=BA00000000000000000000001 |
split.item{item#}.reference |
The reference for that specific transaction split, which is returned in our reporting. Required if the split.item{item#}.type is BalanceAccount. |
split.item1.reference=reference_split_1 split.item2.reference=reference_commission split.item3.reference=reference_PaymentFee |
split.item{item#}.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: Pass the split data
Pass the split data in the SaleData.SaleToAcquirerData object.
You can pass the split data in the SaleData.SaleToAcquirerData object of your terminal API request as concatenated key-value pairs separated by an ampersand (&) character, or in Base64-encoded format.
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
split.api=1
split.nrOfItems=3
split.totalAmount=62000
split.currencyCode=EUR
split.item1.amount=60000
plit.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_PaymentFeeStep 3: Make a payment request
Make a POST request to a Terminal API endpoint, specifying:
-
MessageHeader: the standardSaleToPOIRequest.MessageHeaderobject. This includes:Parameter Required Description ProtocolVersion
3.0 MessageClassService MessageCategoryPayment MessageTypeRequest ServiceIDYour 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.SaleIDYour unique ID for the POS system component to send this request from. POIIDThe 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.SaleTransactionIDAn 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.SaleToAcquirerDataProvides 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.AmountsReqAn 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:
{
"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 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 formattenderReference.pspReference. For example, oLkO0012498220087000.981517998282382C.PaymentResponse.Response.Result: SuccessPaymentResponse.Response.AdditionalResponse: additional transaction data. Its format corresponds to the format of theSaleToAcquirerDatain 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.
Handling tips (gratuity)
When a customer includes a tip in their payment, it is booked to your liable account by default. However, you can book the entire tip amount directly to your user's balance account by providing an additional split item in the payment request.
Before you begin
Before you can split a payment that includes a tip, you must:
- Read and understand our Terminal API fundamentals.
- Configure the method of tipping (POS app or terminal). A tip made on the receipt cannot be booked directly to your user.
Book the tip to your user
To book a payment's tip directly to your user, add an additional split item in the SaleToAcquirerData object of your PaymentRequest. Specify the balance account to which the tip must be booked in the split.item{item#}.account field. You cannot split the tip between multiple balance accounts.
For the tip split item, add the following fields to the string in the SaleToAcquirerData object, either in concatenated key-value pairs or in a base64 encoded format:
| Key | Description | Example |
|---|---|---|
split.nrOfItems |
Number of times you split the payment. Must match the number of split items in the request. Include the tip as an additional split item in the total number of split items. | split.nrOfItems=3 |
split.item{item#}.type |
The type of split. Set this to Tip. | split.item3.type=Tip |
split.item{item#}.account |
Account that will receive the split. This is the balanceAccountID of one of your user's balance accounts. |
split.item3.account=BA00000000000000000000001 |
split.item{item#}.reference |
Your reference for the tip, reflected in the Balance Platform Accounting Report. | split.item3.reference=reference_tip |
split.item{item#}.description |
Your description for the tip, reflected in the Balance Platform Accounting Report. | split.item3.description=description_tip |
You do not need to include the tip amount in the split.totalAmount or split.item{item#}.amount fields, since the tip amount may not be known when creating the payment request.
For example, a payment of EUR 630.00 is split into:
- EUR 600.00 to be paid to your user's first balance account as the sale amount.
- EUR 10.00 to be paid to your user's first balance account as the tip.
- EUR 20.00 to be paid to your liable account as your platform's commission.
In this case, set the split.nrOfItems to 3 and split.totalAmount to 62000.
Adjust the POST /payments request depending on the configured method of tipping:
When the tip is implemented from the POS app, include an additional AmountsReq.TipAmount object, where you specify the amount of the tip.
{
"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=Tip&split.item3.account=BA00000000000000000000001&split.item3.reference=reference_tip&split.item3.description=description_tip"
},
"PaymentTransaction": {
"AmountsReq": {
"Currency": "EUR",
"RequestedAmount": 620.00
"TipAmount": 10.00
}
}
}
}
}{
"SaleToPOIResponse":{
"MessageHeader":{...},
"PaymentResponse":{
"POIData":{
"POIReconciliationID":"1000",
"POITransactionID":{
"TimeStamp":"2023-03-14T16:10:31.279Z",
"TransactionID":"qwiT001678810231002.8826788102602493"
}
},
"PaymentReceipt":[...],
"PaymentResult":{
"AmountsResp":{
"AuthorizedAmount":630,
"Currency":"EUR",
"TipAmount":10
},
...
"PaymentAcquirerData":{
"AcquirerPOIID":"S1F2-000158212618765",
"AcquirerTransactionID":{
"TimeStamp":"2023-03-14T16:10:31.279Z",
"TransactionID":"8826788102602493"
},
"ApprovalCode":"123456",
"MerchantID":"AdyenTechSupport_NainaBP_TEST"
},
"PaymentInstrumentData":{...}
},
"Response":{
"AdditionalResponse":"AID=A000000004101001&acquirerCode=TestPmmAcquirer&acquirerResponseCode=APPROVED&applicationLabel=mc%20en%20gbr%20gbp&applicationPreferredName=MCENGBRGBP&authCode=123456&avsResult=0%20Unknown&backendGiftcardIndicator=false&batteryLevel=2%25&cardBin=541333&cardHolderVerificationMethodResults=420300&cardIssueNumber=33&cardIssuerCountryId=826&cardScheme=mc&cardSummary=9999&cardType=mc&cvcResult=0%20Unknown&expiryMonth=02&expiryYear=2028&fundingSource=CREDIT&giftcardIndicator=false&gratuityAmount=1000&iso8601TxDate=2023-03-14T16%3a10%3a31.279Z&issuerCountry=GB&merchantReference=565&mid=50&offline=false&paymentMethod=mc&paymentMethodVariant=mc&posAmountCashbackValue=0&posAmountGratuityValue=1000&posAuthAmountCurrency=EUR&posAuthAmountValue=63000&posEntryMode=CLESS_CHIP&posOriginalAmountValue=62000&posadditionalamounts.gratuityAmount=1000&posadditionalamounts.originalAmountCurrency=EUR&posadditionalamounts.originalAmountValue=62000&pspReference=8826788102602493&refusalReasonRaw=APPROVED&retry.attempt1.acquirer=TestPmmAcquirer&retry.attempt1.acquirerAccount=TestPmmAcquirerAccount&retry.attempt1.rawResponse=APPROVED&retry.attempt1.responseCode=Approved&shopperCountry=NL&store=NL_store_1&tc=D23562430A4F269E&tid=12618765&transactionReferenceNumber=8826788102602493&transactionType=GOODS_SERVICES&txdate=14-03-2023&txtime=17%3a10%3a31",
"Result":"Success"
},
"SaleData":{
"SaleTransactionID":{
"TimeStamp":"2023-03-14T16:10:31.537Z",
"TransactionID":"565"
}
}
}
}
}