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.

There are two forms of tipping from the payment terminal. You can choose either:

  • Direct tipping: The shopper directly chooses or enters a tip amount, or skips giving a tip.
  • Indirect tipping: The shopper indirectly gives a tip by entering a total amount that's higher than the original purchase amount. This is customary in Nordic countries.

Your payment request is the same in both cases.

Direct tipping

Direct tipping can happen before or after the shopper 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. Define tipping options (optional).
  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 defined, 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. Define tipping options (optional).
  3. Make payment requests using the tender option AskGratuity.

Define tipping options for direct tipping

It's possible to use direct tipping without tipping options. The payment terminal then shows a prompt for a tip plus an option to skip giving a tip. To give a tip, the customer needs to enter the amount and confirm. If this is what you want, do not define any tipping options. The tender option AskGratuity in your payment request is enough to trigger this behavior.

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 predefine tipping options:

  1. Log in to your Customer Area.
  2. Optionally switch to the merchant account that you want to define tipping options for.
  3. Go to Point of sale > Terminal settings or select a specific terminal.
  4. Under Payment features > Tipping, select Add currency.
  5. Define your options:
    • You can define different options for different currencies.
    • You can define two sets of tipping options per currency, below and above a threshold amount.
    • Per set, 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 shows a screen where the shopper can enter a tip amount).
    • To define the same options regardless of the purchase amount, select Above and an amount of 0 (zero).
  6. 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.

    For more information on the Terminal API request structure, refer to the Terminal API fundamentals.

    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