Search

Are you looking for test card numbers?

Would you like to contact support?

Point-of-sale icon

Tipping from the terminal

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

Depending on what's customary in your region, you can let your customers add a tip on the payment terminal in the following ways:

  • Customer enters 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). We refer to this as direct tipping.
  • Customer enters a total amount: If the customer wants to give a tip, they enter a total amount that's higher than the original purchase amount. This is customary in Nordic countries. We refer to this as indirect tipping

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

Direct tipping

Direct tipping 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 use direct tipping before card entry:

  1. Configure direct tipping.
  2. 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. After that, the terminal asks the customer to complete the payment by providing their PIN or signature, if required.

To use direct tipping after card entry:

  1. Contact our POS Support Team and ask them to enable tipping options after card entry.
  2. Configure direct tipping.
  3. Make payment requests using the tender option AskGratuity.

Configure direct tipping

It's possible to use direct tipping without tipping options. The payment terminal then shows a prompt to enter a tip plus an option to skip giving a tip. To give a tip, the customer needs to enter the amount and confirm.

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.

Direct tipping without options:
Direct tipping with predefined options:

To configure direct tipping:

  1. Log in to your Customer Area.
  2. Optionally switch to the merchant account, store, or terminal that you want to configure tipping for.
  3. Go to Point of sale > Terminal settings.
  4. Go to Payment features > Tipping.
  5. At Enable tipping, select Enabled.
  6. At Type of tipping, select the tipping screen you want to show to your customers:
    • Shopper enters tip amount: Shows the screen for direct tipping without options.
    • Shopper selects a predefined option: Shows the screen for direct tipping with predefined options.
  7. Select the Currency that the settings should apply to.
  8. 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 to skip 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).
  9. Optional. If applicable, select Add another currency, select a currency, and configure tipping for that currency.
  10. Select Save.

Indirect tipping

With indirect tipping 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 indirect tipping:

  1. Contact our POS Support Team and ask them to enable indirect tipping.
  2. Make payment requests using the tender option AskGratuity.

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

Indirect tipping for currency with decimals:
Indirect tipping for currency without decimals:

Make a payment

To trigger the payment terminal to prompt your customer as expected for direct or indirect tipping, you need to make a payment request with the AskGratuity tender option.

  1. Make a PaymentRequest with:

    • PaymentRequest: The request body. This includes:

      Parameter Required Description
      SaleData.SaleToAcquirerData The AskGratuity tender option that triggers the terminal to start the tipping flow.

      See the instructions below.

      PaymentTransaction.AmountsReq -white_check_mark- 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, refer to Add information to a payment.

    The example below shows how you would show tipping options and initiate a 142.50 EUR transaction.

    Payment request with tipping
    {
      "SaleToPOIRequest":{
        "MessageHeader":{
          "ProtocolVersion":"3.0",
          "MessageClass":"Service",
          "MessageCategory":"Payment",
          "MessageType":"Request",
          "SaleID":"POSSystemID12345",
          "ServiceID":"0207111104",
          "POIID":"P400Plus-275688710"
        },
        "PaymentRequest":{
          "SaleData":{
            "SaleTransactionID":{
              "TransactionID":"27908",
              "TimeStamp":"2019-12-17T10:11:03.000Z"
            },
            "SaleToAcquirerData": "tenderOption=AskGratuity,ReceiptHandler"
          },
          "PaymentTransaction":{
            "AmountsReq":{
              "Currency":"EUR",
              "RequestedAmount":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.

  2. 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 authorised amount of the transaction: The original purchase amount plus the tip amount.
      • Currency: Currency of the payment.

    • Response.AdditionalResponse: Additional transaction data. You'll 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: Original purchase amount in minor units.
      • posAmountGratuityValue: Tip amount in minor units.
      • authorisedAmountValue: Total authorised amount in minor units.

    The example below shows the response for a 142.50 EUR transaction with a 10% tip added.

    Payment response with tip added
    {
      "SaleToPOIResponse": {
        "PaymentResponse": {
          "POIData": {
            "POITransactionID": {
              "TimeStamp": "2019-12-17T10:11:12.000Z",
              "TransactionID": "8ha5001575467786000.8815754678001083"
            }
              {...},
          "SaleData": {...},
            "PaymentReceipt": [...],
            "PaymentResult": {
              "AuthenticationMethod": [...],
              "OnlineFlag": true,
              "PaymentAcquirerData": {...},
              "PaymentInstrumentData": {...},
              "AmountsResp": {
                "TipAmount": 14.25,
                "AuthorizedAmount": 156.75,
                "Currency": "EUR"
              }
            },
            "Response": {
              "Result": "Success",
              "AdditionalResponse": "...posadditionalamounts.originalAmountValue=14250&...posAmountGratuityValue=1425&gratuityAmount=1425&...authorisedAmountValue=15675...&posAuthAmountValue=15675&posadditionalamounts.gratuityAmount=1425"
            }
          },
        "MessageHeader": {...}
      }
    }

Keeping your staff informed with webhooks

While your shopper is interacting with the terminal, you may want to present progress messages on your cash register. These can keep your staff informed of the tip amount.

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, refer to our display notifications documentation.

See also