Terminal-2 icon

Tipping from the POS app

Implement tipping from the POS app in your payment flow.

Here we describe how to implement tipping in your payment flow where the payment request that you send from your POS app includes a tip amount. The terminal shows the original transaction amount and the tip amount. The customer then uses the terminal to confirm the tip, change the amount, or decline giving a tip.

Requirements

Before you implement tipping, make sure you have:

Configure tipping

The tip amount to propose to your customer on the terminal can be a percentage of the transaction amount, a fixed amount, one of various fixed amounts depending on the transaction amount, and so on.
You need to implement logic on your end to ensure your POS app provides the tip amount that you need to include in your payment request.

Make a payment

After you configured tipping in your POS system, you are ready to make a payment request that includes a TipAmount. This shows the transaction amount and the proposed tip amount on the terminal display.

  1. Make a POST request to a Terminal API endpoint, specifying:

    • MessageHeader: the standard SaleToPOIRequest.MessageHeader object. Specify:

      Parameter Required Description
      ProtocolVersion -white_check_mark- 3.0
      MessageClass -white_check_mark- Service
      MessageCategory -white_check_mark- Payment
      MessageType -white_check_mark- Request
      ServiceID -white_check_mark- 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 -white_check_mark- Your unique ID for the POS system component to send this request from.
      POIID -white_check_mark- The unique ID of the terminal to send this request to. Format: [device model]-[serial number].

    • PaymentRequest:

      Parameter Required Description
      SaleData.SaleTransactionID -white_check_mark- An object with:
      • TransactionID: your reference to identify a payment. We recommend using a unique value. In your Customer Area and Adyen reports, this will show as the merchant reference for the transaction.
      • TimeStamp: date and time of the request in UTC format.
      PaymentTransaction.AmountsReq -white_check_mark- An object with:
      • Currency: the transaction currency.
      • RequestedAmount: the transaction amount.
      • TipAmount: the tip amount.

    The example below shows how to initiate a payment of EUR 142.50 with a 10% tip.

    The payment request is routed to the payment terminal. The customer accepts, changes, or declines the tip and completes the payment. The terminal then collects the payment details and sends the request for the original transaction 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:

    • 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: 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 transaction 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 EUR142.50 transaction with a 10% tip added.

See also