---
title: "Tipping from the POS app"
description: "Implement tipping from the POS app in your payment flow."
url: "https://docs.adyen.com/point-of-sale/tipping/tipping-from-cash-register"
source_url: "https://docs.adyen.com/point-of-sale/tipping/tipping-from-cash-register.md"
canonical: "https://docs.adyen.com/point-of-sale/tipping/tipping-from-cash-register"
last_modified: "2023-04-17T10:40:00+02:00"
language: "en"
---

# Tipping from the POS app

Implement tipping from the POS app in your payment flow.

[View source](/point-of-sale/tipping/tipping-from-cash-register.md)

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 begin, take into account the following requirements, limitations, and preparations.

| Requirement          | Description                                                                                   |
| -------------------- | --------------------------------------------------------------------------------------------- |
| **Integration type** | A [Terminal API](/point-of-sale/design-your-integration/terminal-api) with payment terminals. |
| **Hardware**         | All terminal models are supported, except unattended terminals.                               |
| **Setup steps**      | Implement logic in your POS app to provide the tip amount for payment requests.               |

## Set up tipping in your POS app

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 payment request](/point-of-sale/basic-tapi-integration/make-a-payment), specifying:

   * The standard [`SaleToPOIRequest.MessageHeader` ](/point-of-sale/design-your-integration/terminal-api#request-message-header)object, with `MessageClass` set to **Service** and `MessageCategory` set to **Payment**.

     | Parameter         | Required                                                                                    | Description                                                                                                                                                 |
     | ----------------- | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
     | `ProtocolVersion` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | **3.0**                                                                                                                                                     |
     | `MessageClass`    | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | **Service**                                                                                                                                                 |
     | `MessageCategory` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | **Payment**                                                                                                                                                 |
     | `MessageType`     | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | **Request**                                                                                                                                                 |
     | `ServiceID`       | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-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-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | Your unique ID for the POS system component to send this request from.                                                                                      |
     | `POIID`           | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The unique ID of the terminal to send this request to. Format: *\[device model]-\[serial number]*.                                                          |

   - The [PaymentRequest](https://docs.adyen.com/api-explorer/terminal-api/latest/post/payment) object with:

     | Parameter                       | Required                                                                                    | Description                                                                                                                                                                                                                                                                                                                                                   |
     | ------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
     | `SaleData.SaleTransactionID`    | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-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](https://en.wikipedia.org/wiki/ISO_8601#Coordinated_Universal_Time_\(UTC\)). |
     | `PaymentTransaction.AmountsReq` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | An object with:- `Currency`: the transaction [currency](/development-resources/currency-codes).
     - `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.

   **Payment request with tipping**

   ```json
   {
     "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"
           }
         },
         "PaymentTransaction":{
           "AmountsReq":{
             "Currency":"EUR",
             "RequestedAmount":142.50,
             "TipAmount":14.25
           }
         }
       }
     }
   }
   ```

   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 successful, the terminal shows the payment is approved.

2. In the [PaymentResponse](https://docs.adyen.com/api-explorer/terminal-api/latest/post/payment#responses-200) note the following:

   * `POIData.POITransactionID.TransactionID`: [Transaction identifier](/point-of-sale/design-your-integration/terminal-api#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`: the amount of the tip. If the customer didn't add a tip, this field is not included.

     * `AuthorizedAmount`: the total amount of the payment, consisting of the original transaction amount plus the tip amount.

     * `Currency`: the 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](/development-resources/currency-codes).
     * `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.

   **Payment response with tip added**

   ```json
   {
     "SaleToPOIResponse": {
       "PaymentResponse": {
         "POIData": {
           "POITransactionID": {
             "TimeStamp": "2019-12-17T10:11:12.000Z",
             "TransactionID": "8ha5001575467786000.NC6HT9CRT65ZGN82"
           },
         "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": {...}
       }
   }
   ```

## Add tip amounts to reporting

The [Settlement details report](/reporting/settlement-reconciliation/transaction-level/settlement-details-report/#generate-and-download-reports) is an overview of payments details that have been settled and paid out to you by Adyen, and the cost of each transaction. When you generate a Settlement details report, you can include an overview of tips by adding the **gratuity amount** column to your report in your [Customer Area](https://ca-test.adyen.com/).

For more information on how to add the **gratuity amount** column to your report, see [Configure report columns](/reporting/settlement-reconciliation/transaction-level/settlement-details-report/#configure-report-columns).

## See also

* [Make a payment](/point-of-sale/basic-tapi-integration/make-a-payment)
* [Settlement details report](/reporting/settlement-reconciliation/transaction-level/settlement-details-report/)
