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.

Here we describe how to implement tipping in your payment flow where the payment terminal shows predefined tipping options for the customer to choose from. These options can be fixed amounts or percentages of the transaction amount, or both. After the customer has selected an option or entered a custom tip amount, the terminal sends the transaction amount and the tip amount to the Adyen payments platform for authorisation. In this way the total amount is authorised and automatically captured.

Step 1: Configure tipping from the terminal

Before you can make a payment request that triggers the terminal to show tipping options, you need to:

Define tipping options

Tipping options on the terminal display

If you enable tipping without defining tipping options, the display of the payment terminal shows a simple prompt to enter the tip amount plus a 'no tip' option to decline giving a tip.

To make tipping easier, you can predefine or calculate tip amounts that your customer can select on the terminal. To do so, you need to define tipping options in a JSON file:

  • Options can be for a specific amount, for a percentage of the purchase, for a 'custom tip', or for 'no tip'.
  • The no_tip option is required.
  • The custom_tip option will show a screen where the shopper can enter a tip amount.
  • If the option is for a percentage, the display will show the percentage plus the calculated amount of the tip.
  • We recommend using four options plus 'no tip' as the last option.
  • You can define two sets of tipping options, below and above a threshold amount. The limit field specifies this threshold. If you want the same options always, specify the same values in the below and above arrays.
  • You can create different JSON files for different merchant accounts.

Use the following example to create your tipping options JSON file.

{
   "USD":{
      "limit":2000,
      "below":[
         "100",
         "200",
         "300",
         "custom_tip",
         "no_tip"
      ],
      "above":[
         "10%",
         "15%",
         "20%",
         "custom_tip",
         "no_tip"
      ]
   }
}

Enable tipping

You need to make some changes to your account to enable tipping from the terminal.

  • Contact our POS Support Team and:
    • Ask them to enable tipping for your terminals.
    • Tell them whether you want tipping before or after card entry.
      • Before card entry: The terminal shows the transaction amount plus the tipping options and waits for the customer to respond. Then the terminal asks the customer to present their card and provide their PIN or signature.
      • After card entry: The terminal shows the transaction amount and asks the customer to present their card. Then the terminal shows the tipping options and waits for the customer to respond. After that, the terminal asks the customer to provide their PIN or signature.
    • Send them your tipping options JSON file if you want to show predefined tipping amounts or percentages on the payment terminal.

Keep 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.

Step 2: Make a payment

After you configured tipping from the terminal, you are ready to make a payment request with the AskGratuity tender option. This ensures that the terminal presents tipping options to your customer.

  • Make a POST request to a Terminal API endpoint, specifying:

    • MessageHeader: This follows the standard MessageHeader structure, explained in Terminal API fundamentals, which includes:

      • ProtocolVersion: 3.0
      • MessageClass: Service
      • MessageCategory: Payment.
      • MessageType: Request
      • SaleID: Your unique ID for the cash register.
      • ServiceID: Your unique ID for this transaction attempt, consisting of 1-10 alphanumeric characters. This value needs to be unique within the last 48 hours.
      • POIID: Unique ID of the terminal.¬†This indicates which terminal the payment will be routed to.
    • PaymentRequest: The request body for the payment request must include:

      • SaleData.SaleTransactionID.TransactionID: Your unique reference for this payment request.
      • SaleData.SaleTransactionID.TimeStamp: Date and time of the payment request, in UTC format.
      • SaleData.SaleToAcquirerData: tenderOption=AskGratuity or tenderOption=AskGratuity,ReceiptHandler where:

        • AskGratuity: Triggers the terminal to show the tipping options you configured.

          If you configured tipping from the terminal but want to make a payment request without showing the tipping screen, omit the AskGratuity tender option from your request.

        • ReceiptHandler: Ensures it's the cash register that prints the receipt. Omit this tender option if the payment terminal has an integrated printer and you want to print the receipt from the terminal.
      • PaymentTransaction.AmountsReq.Currency: The currency of the transaction.
      • PaymentTransaction.AmountsReq.RequestedAmount: The transaction amount.

    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.

    {
      "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 selected a tipping option and presented their card, the payment terminal collects the payment details and sends the request for the original transaction amount plus the tip amount to the Adyen payments platform.

Step 3: Receive payment result

When the payment has been processed on the Adyen payments platform, you receive the payment result in a synchronous API response.

If your integration uses asynchronous cloud communications, you receive the result in a TENDER_FINAL display notification.

If the payment is successful:

  • Approved is displayed on the terminal display.
  • The payment result contains:

    • POIData.POITransactionID.TransactionID: Transaction identifier for the payment.
    • PaymentReceipt: Receipt data with the original transaction amount, the tip amount (not included if the customer didn't add a tip), and the total amount.
    • PaymentResult.AmountsResp:

      • TipAmount: Amount of the tip. If the customer didn't add a tip, this field is not included.
      • AuthorizedAmount: Total amount of the payment (original transaction amount plus tip amount).
      • Currency: Currency of the payment.

    • Response.Result: Success
    • Response.AdditionalResponse: A base64 string. When decoded, this is a JSON object with additional transaction data. This includes:
      • posadditionalamounts.originalAmountValue: Original transaction 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.

    {
      "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": {...}
      }
    }

See also