Split payments at authorization

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.

Requirements

Take into account the following requirements, limitations, and preparations to start processing payments.

How it works

To provide the split instructions 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 80.00, split three ways:

• EUR 75.00 is booked to your user's balance account as payment for the goods or services.
• EUR 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 data

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

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:

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.

3. Make a payment request

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

• MessageHeader
• PaymentRequest

MessageHeader

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

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].

PaymentRequest

PaymentRequest is the request body, which includes:

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 steps 1 and 2 for instructions.
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 EUR 10, enter 10.00 (not 1000).

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

• EUR 75.00 is booked to your user's balance account as payment for the goods or services.
• EUR 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, for the customer to present their card and verify the payment. The payment is then sent to the Adyen payments platform for processing.

Troubleshooting

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.

4. Check the payment result

To learn if the payment is successful, check the following fields in the API response:

• Approved is shown on the terminal display.
• You receive a payment response with:
  • POIData.POITransactionID.TransactionID: The transaction identifier for the payment in the format tenderReference.pspReference. For example, oLkO0012498220087000.981517998282382C.
  • PaymentResponse.Response.Result: Set to Success
  • PaymentResponse.Response.AdditionalResponse: The 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: The object with data you can use to generate a receipt.

{
  "SaleToPOIResponse":{
    "MessageHeader":{...},
    "PaymentResponse":{
      "POIData":{
        "POITransactionID":{
          "TransactionID": "oLkO0012498220087000.981517998282382C"
        },
        ...
      },
      "Response":{
        "Result":"Success",
      },
      ...
    },
    "PaymentReceipt":{...}
  }
}

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.

Track fund movements

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

1. 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.
2. Acknowledge the webhooks. We send these webhooks for every split item in the payment.
3. In the balancePlatform.transfer.updated webhook payload, note that the event array includes all previous transfer events, and 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 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 instructions at capture instead. Split data 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.

See also