Tipping from the terminal

Implement tipping where the customer adds a tip on the payment terminal.

Depending on what is customary in your region, there are various ways to let the payment terminal ask your customers to add a tip:

Ask for a tip amount: the customer chooses a predefined tipping option on the display or enters a custom tip amount (or chooses to skip giving a tip).
Ask for a total amount: if the customer wants to give a tip, they enter a total amount that is higher than the original purchase amount. This is customary in Nordic countries/regions.

The payment request to trigger tipping, is the same in both cases.

Ask for a tip amount

Asking for a tip can happen before or after the customer enters their card. The default is tipping before card entry.

Before card entry

The terminal shows the purchase amount plus the tipping prompt or options you configured, and waits for the customer to respond. Then the terminal asks the customer to present their card and, if required, complete the payment by providing their PIN or signature.
No configuration from our side is needed for this.

To ask for a tip before card entry:

Configure tipping in your Customer Area.
Make payment requests using the tender option AskGratuity.

After card entry

The terminal shows the purchase amount and asks the customer to present their card. Then the terminal shows the tipping prompt or options you configured, and waits for the customer to respond. If required, the terminal asks the customer to complete the payment by providing their PIN or signature.

To ask for a tip after card entry:

Contact our Support Team and ask them to:
- Enable tipping options after card entry.
- (Optional) Enable single tap. For contactless transactions, this ensures the terminal doesn't ask the customer to tap their card again after selecting a tip.
Configure tipping in your Customer Area.
Make payment requests using the tender option AskGratuity.

Configure tipping

It is possible to ask for a tip without tipping options. The payment terminal then shows a prompt to enter a tip plus an option for not giving a tip. To give a tip, the customer enters the amount and confirms.

To make tipping easier for your customers, you can define tipping options that your customer can select on the terminal. The options can be any combination of percentages, fixed amounts, and a custom amount.


Tipping prompt without options:	Tipping with predefined options:

To configure asking for a tip amount:

Log in to your Customer Area.
Optionally switch to the merchant account, store, or terminal that you want to configure tipping for.
Go to In-person payments > Terminal settings.
Go to Payment features > Tipping.
At Enable tipping, select Enabled.
Select the Currency that the settings should apply to.
At Type of tipping, select the tipping screen you want to show to your customers:
- Shopper enters tip amount: shows the screen for tipping without options.
- Shopper selects a predefined option: shows the screen for tipping with predefined options.
If you selected Shopper selects a predefined option, define the options:
- You can define different options for different currencies, except at store or terminal level where only one currency applies.
- Per currency, you can define a maximum of four options. We automatically add an option for not giving a tip.
- An option can be for a specific amount, for a percentage of the purchase (the terminal shows the percentage plus the calculated amount), or for a custom tip (this leads the customer to a screen where they can enter a tip amount).
Optional. If applicable, select Add another currency, select a currency, and configure tipping for that currency.
Optional. At Enable standalone tipping select Enabled if it fits your use case.
Select Save.

You can configure your POS app to override the tipping settings that you have defined in your Customer Area.

Ask for a total amount

The terminal shows the original purchase amount and a prompt to enter the total amount. This must at least be equal to the original amount. By entering a higher total amount, the customer adds a tip. After the customer enters the total amount, the terminal asks the customer to present their card and, if required, complete the payment by providing their PIN or signature.

To use tipping by asking for a total amount:

Contact our Support Team to enable tipping by asking for a total amount.
Make payment requests using the tender option AskGratuity.

For currencies that in practice do not use decimals in transactions (like SEK), we make sure the tipping screen doesn't show decimals.


Total tipping for currency with decimals:	Total tipping for currency without decimals:

Make a payment

To trigger the payment terminal to ask the customer for a tip amount or a total amount, you need to make a payment request with the AskGratuity tender option.

Make a PaymentRequest with:

MessageHeader: the standard SaleToPOIRequest.MessageHeader object. Specify:

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	Description
`SaleData.SaleToAcquirerData`	The AskGratuity tender option that triggers the terminal to start the tipping flow. See the instructions below.
`PaymentTransaction.AmountsReq`	An object with: `Currency`: The transaction currency. `RequestedAmount`: The purchase amount, with decimals.

In SaleData.SaleToAcquirerData, specify the tender option in one of the following formats:

Option 1: a JSON object converted to a Base64 encoded string.
Encode {"tenderOption": "AskGratuity"} to Base64, and pass the resulting string:
"SaleToAcquirerData": "eyJ0ZW5kZXJPcHRpb24iOiAiQXNrR3JhdHVpdHkifQ=="
Option 2: a key-value pair:
"SaleToAcquirerData": "tenderOption=AskGratuity"

The format that you use here, will also be the format of the AdditionalResponse that you receive. If there are more tender options (for example ReceiptHandler ) or other data elements that you need to pass in the SaleToAcquirerData field, see Add information to a payment.

The example below shows how to show tipping options and initiate a transaction of EUR 142.50.

When the customer has responded, the payment terminal sends the request for the original purchase amount plus the tip amount to the Adyen payments platform.

If the payment is successful, the terminal shows Approved.

In the PaymentResponse note the following:
- PaymentReceipt: receipt data with the original purchase amount, the gratuity amount, and the total amount. If the customer didn't add a tip, the gratuity amount is not included.
- PaymentResult.AmountsResp:
  - TipAmount: amount of the tip. If the customer didn't add a tip, this field is not included.
  - AuthorizedAmount: total authorized amount of the transaction: The original purchase amount plus the tip amount.
  - Currency: currency of the payment.
- Response.AdditionalResponse: additional transaction data. Depending on the format you used in the request, you receive either a string of form-encoded key-value pairs or a Base64 string that you need to decode to get a JSON object. This includes:
  - posadditionalamounts.originalAmountValue: the original purchase amount in minor units.
  - posAmountGratuityValue: the tip amount in minor units.
  - authorisedAmountValue: the total authorized amount in minor units.
The example below shows the response for a transaction of EUR 142.50 with a 10% tip added.

Keeping your staff informed with webhooks

While your customer is interacting with the terminal, you can keep your staff informed of the tip amount by showing progress messages in your POS app.

These messages are delivered using display notifications, which are webhooks that are sent to an endpoint that you specify. For information on how to set up and use display notifications, see our display notifications documentation.

High tip warning screen

When tipping from a terminal, it can happen that customers accidentally enter a tip amount that is too high. To prevent making a payment with incorrect amounts, the terminal can show a warning screen if the tip amount is higher than a certain percentage of the original purchase amount.
For example, you can set the warning screen threshold to 50% of the original purchase amount. If the original amount is EUR 100.00 and the customer enters a tip of EUR 50.00 or more, the terminal shows the warning screen. The customer can then confirm the amount or go back to the previous screen.

When enabled, the warning screen works with both methods of tipping from the terminal (asking for a tip amount, and asking for a total amount). This feature is available on standalone terminals as well as terminals integrated with a POS system.

To show the high tip warning screen:

Enable tipping by asking for a tip amount or total amount.
Ask our Support Team to enable the warning screen for tips that are higher than the percentage you want of the original purchase amount.
Make payment requests using the tender option AskGratuity.