Tipping

Implement tipping (gratuity) in your payment flow.

When a customer adds a tip (gratuity) to 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.

You can book the tip to your user's balance account when you use one of the following tipping methods:

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.
Limitations	Booking the tip to your user's balance account is not supported with tipping on the receipt.
Setup steps	Check the flow, the requirements, and the setup or configuration steps for your chosen tipping method: tipping from the POS app or tipping from the terminal.

Tip from POS app and book to your user

To make payment request that adds a tip and split instructions for how to book the tip when you use tipping from the POS app:

When you gather the split instructions for the payment, add a split item for the tip:

Increase the split.nrOfItems by one, to accommodate the tip split item you are adding.

In the split item for the tip, specify:

Key	Description
`split.item[ITEM_NUMBER].type`	The type of split. Set this to Tip.
`split.item[ITEM_NUMBER].account`	The account that will receive the tip. This is the `balanceAccountID` of one of your user's balance accounts. You cannot split the tip between multiple balance accounts.
`split.item[ITEM_NUMBER].reference`	Your reference for the tip, reflected in the Balance Platform Accounting Report.
`split.item[ITEM_NUMBER].description`	Your description of the tip, reflected in the Balance Platform Accounting Report.

Do not include the tip amount in the split.totalAmount field and do not add a split.item[ITEM_NUMBER].amount field for the tip.

Format the split instructions in one of the following ways:
- 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.
As an example, we use a payment of USD 630.00 that is split into:
- USD 600.00 to be paid to your user's first balance account as the sale amount.
- USD 20.00 to be paid to your liable account as your platform's commission.
- The payment fee to be booked to your user's first balance account. This will be deducted from the sale amount.
- USD 10.00 to be paid to your user's second balance account as the tip.
In this case, the split.nrOfItems is 4 and the split.totalAmount is 62000, because the payment fee is not known yet, and the tip amount should not be added even if you do know it in advance.

Make a Terminal API payment request, including:

The PaymentRequest object with:

Parameter	Required	Description
`SaleData.SaleToAcquirerData`		The formatted string of split instructions for the payment.
`PaymentTransaction.AmountsReq.Currency`		The transaction currency.
`PaymentTransaction.AmountsReq.RequestedAmount`		The transaction amount.
`PaymentTransaction.AmountsReq.TipAmount`		The tip amount.

In the PaymentResponse note the following:
- PaymentResult.AmountsResp:
  - TipAmount: The amount of the tip. If the customer declined adding a tip, this field is not included.
  - AuthorizedAmount: The total amount of the payment (original transaction amount plus tip amount).
  - Currency: The currency of the payment.
- Response.AdditionalResponse:
  - posadditionalamounts.originalAmountValue: The original transaction amount in minor units.
  - posAmountGratuityValue: The tip amount in minor units.
  - authorisedAmountValue: The total authorised amount in minor units.

Tip from terminal and book to your user

To make payment request that adds a tip and split instructions for how to book the tip when you use tipping from the terminal: