Split a payment

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.item2.amount=2000
     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.item1.type=BalanceAccount split.item2.type=Commission split.item3.type=PaymentFee
     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.item3.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.item2.reference=reference_commission split.item3.reference=reference_PaymentFee
     split.item[ITEM_NUMBER].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

     The data for the split payment

     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_PaymentFee

     https://docs.adyen.com/pt/pt/marketplaces-and-platforms/processing-ipp/split-a-payment#split-data-pairs-1

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.

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		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: The request body. This 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 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 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.

The final split amounts may not be clear at the moment the payment request is made, for example, in the case of 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. The split information you provide at capture overrides any split information you may have provided in your payment request.

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:

Step 1: Get the pspReference

From the `transactionID` field in the payment response , get the pspReference of the authorisation you want to capture.

Step 2: Send the payment request

Make a POST request to the /payments/paymentPspReference/captures endpoint, where paymentPspReference is the pspReference of the authorisation you want to capture.

In your request, include:

Parameter	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. account: the balance 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 a balance account when split.type is Commission. reference: an optional reference which is returned in our reporting. You can use this to refer to that specific transaction split.

The example below shows how to capture a 620.00 EUR authorisation with pspReference 981517998282382C, and split it into 600.00 EUR to be paid into the user's balance account with balanceAccountId 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"
        }
      ]
}'

Step 3: Check the result

Response

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.

Webhook

Wait for the CAPTURE webhook to learn the outcome of the request.