In a platform setup, you can onboard your users with point-of-sale integrations to accept in-person payments. With every payment and capture, you can split the funds between any number of balance accounts in your platform, including your liable balance account. For example, when a customer pays, you can split the funds into two parts: one part is the platform fee that goes to your liable account, and the other part is the sale amount that goes to your user's balance account.
You must send the split information for every transaction at the time of payment or at capture. If the payments are not split, the full amount is booked to your liable account.
Before you begin
Before you start processing point-of-sale payments for your user, make sure that you have:
- A Terminal API integration with Adyen.
- Created your user's store and business line and configured them to accept point-of-sale payments.
- Configured the payment methods your user can accept.
Split at payment
To split funds at the time of payment:
-
Make a POST request to a Terminal API endpoint, specifying:
-
MessageHeader
: the standardSaleToPOIRequest.MessageHeader
object. -
PaymentRequest
: Content of the payment request message. This object contains the split payment data in theSaleToAcquirerData
parameter in key-value pairs or in a Base64-encoded format.
In the
MessageHeader
, include:Parameter Required Description ProtocolVersion
Set to 3.0 MessageClass
Set to Service MessageCategory
Set to Payment MessageType
Set to 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]. In the
PaymentRequest
, include: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
: date and time of the request in UTC format.
SaleData.SaleToAcquirerData
Provides the split payment data as concatenated key-value pairs separated by an ampersand (&) character, or in Base64-encoded format. See the tables below for details. 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 10 EUR specify 10.00 (not 1000).
Provide the split payment data in
PaymentRequest.SaleData.SaleToAcquirerData
: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 and to the sum of the split amounts. split.totalAmount=62000 split.currencyCode
Currency of the amount to be split. split.currencyCode=EUR split.nrOfItems
Number of times you will split the payment. Must match the number of split items in the request. split.nrOfItems=2 In the same
PaymentRequest.SaleData.SaleToAcquirerData
object, specify each split as asplit.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 the split, in minor units. split.item1.amount=60000 and split.item2.amount=2000 split.item{item#}.type
Split type. - BalanceAccount : sends the amount to the
account
specified. - PaymentFee: books the transaction fees to the specified balance account.
- Commission : sends the amount to your liable account.
split.item1.type=BalanceAccount and split.item2.type=Commission split.item{item#}.account
Account that will receive 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 thesplit.item{item#}.type
is Commission.split.item1.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.Example
The example below shows how to split a 620.00 EUR payment into 600.00 EUR to be paid to your user's balance account and 20.00 EUR commission to be paid to your liable account.
a. Define the pairs of split payment data. In our example:
split.api=1
split.nrOfItems=2
split.totalAmount=62000
split.currencyCode=EUR
split.item1.amount=60000
split.item1.type=BalanceAccount
split.item1.account=BA00000000000000000000001
split.item1.reference=RefSplit1
split.item1.description=TestPayment
split.item2.amount=2000
split.item2.type=Commission
split.item2.reference=TestCommissionb. Concatenate the pairs using ampersands (&) to a string.
split.api=1&split.nrOfItems=2&split.totalAmount=62000&split.currencyCode=EUR&split.item1.amount=60000&split.item1.type=BalanceAccount&split.item1.account=BA00000000000000000000001&split.item1.reference=RefSplit1&split.item1.description=TestPayment&split.item2.amount=2000&split.item2.type=Commission&split.item2.reference=TestCommission
c. Pass the string in
SaleToAcquirerData
.{ "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=2&split.totalAmount=62000&split.currencyCode=EUR&split.item1.amount=60000&split.item1.type=BalanceAccount&split.item1.account=BA00000000000000000000001&split.item1.reference=RefSplit1&split.item1.description=TestPayment&split.item2.amount=2000&split.item2.type=Commission&split.item2.reference=TestCommission" }, "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.
-
-
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 event notifications endpoint.If the payment is successful:
- Approved is shown on the terminal display.
- You receive a payment response containing:
POIData.POITransactionID.TransactionID
: Transaction identifier for the payment in the formattenderReference.pspReference
. For example, oLkO0012498220087000.981517998282382C.PaymentResponse.Response.Result
: SuccessPaymentResponse.Response.AdditionalResponse
: Information resulting from the processing of your payment request. Its format corresponds to the format of theSaleToAcquirerData
in the payment request: a Base64-encoded JSON object or form-encoded key-value pairs.PaymentReceipt
: Object containing 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.
Split at capture
The final split amounts may not be clear at the moment the payment request is made, for example, in the case of tipping (gratuity) and partial payments. If this applies to your user's point-of-sale payments, you need to enable manual capture and follow up with a /payments/paymentPspReference/captures API call containing the split details.
To enable manual capture, you can either:
-
Enable manual capture at the account level. In this case, you must follow up each authorised Terminal API payment with a
/payments/paymentPspReference/captures
API call.Enabling manual capture at the account level applies to all your point-of-sale users.
-
Enable manual capture at the transaction level. In this case, you add a manual capture flag to the payment request and then make a
/payments/paymentPspReference/captures
API call for that specific authorization.
To split a payment at capture:
-
From the
transactionID
field in the payment response , get thepspReference
of the authorisation you want to capture. -
Make a POST request to the /payments/paymentPspReference/captures endpoint, where
paymentPspReference
is thepspReference
of the authorisation you want to capture.
In your request, include:
The example below shows how to capture a 620.00 EUR authorisation withParameter Required Description amount.value
The amount in minor units (without a decimal point) being captured. This must be the same amount as the original authorised amount. amount.currency
This must match the currency of the payment you are capturing. merchantAccount
The name of your merchant account that is used to process the payment. reference
Your unique identifier for the capture operation. splits
An array of split items, each including: amount.value
: the amount of the split, in minor units.type
: the type of split type.- BalanceAccount: sends the amount to the
account
specified. - Commission: sends the amount to your liable account.
- PaymentFee: send the tranaction fees to the specified balance account.
- BalanceAccount: sends the amount to the
account
: the balance account that will receive the split. This is thebalanceAccountId
of one of your user's balance accounts or your own liable account. You don't need to specify a balance account whensplit.type
is Commission.reference
: an optional reference which is returned in our reporting. You can use this to refer to that specific transaction split.
pspReference
981517998282382C, and split it into 600.00 EUR to be paid into the user's balance account withbalanceAccountId
BA00000000000000000000001 and 20.00 EUR commission to be paid to your liable account.curl https://checkout-test.adyen.com/v69/payments/981517998282382C/captures \ -H "x-API-key: YOUR_X-API-KEY" \ -H "content-type: application/json" \ -d '{ "merchantAccount": "YOUR_MERCHANT_ACCOUNT", "amount": { "value": 62000, "currency": "EUR" }, "reference": "YOUR_REFERENCE_NUMBER", "splits":[ { "amount":{ "value":60000 }, "type":"BalanceAccount", "account":"BA00000000000000000000001", "reference":"YOUR_REFERENCE_TO_SPLIT_#1" }, { "amount":{ "value":2000 }, "type":"Commission", "reference":"YOUR_REFERENCE_TO_SPLIT_#2" } ] }'
-
In the capture response, note the following:
paymentPspReference
: the PSP reference of the authorisation.pspReference
: the PSP reference associated with this capture request. This is different from the PSP reference of the authorisation.status
: received. Your capture request will be processed asynchronously. You will receive the result in a webhook.
- Wait for the CAPTURE webhook to learn the outcome of the request.