---
title: "Override configured tipping options"
description: "Offer shoppers tipping options on the terminal to match different tipping scenarios."
url: "https://docs.adyen.com/point-of-sale/tipping/tipping-from-terminal/override-tipping-configuration"
source_url: "https://docs.adyen.com/point-of-sale/tipping/tipping-from-terminal/override-tipping-configuration.md"
canonical: "https://docs.adyen.com/point-of-sale/tipping/tipping-from-terminal/override-tipping-configuration"
last_modified: "2024-10-30T09:25:00+01:00"
language: "en"
---

# Override configured tipping options

Offer shoppers tipping options on the terminal to match different tipping scenarios.

[View source](/point-of-sale/tipping/tipping-from-terminal/override-tipping-configuration.md)

If you have defined default tipping options in your Customer Area, you may want to present different tipping options depending on the type of goods or services that a shopper buys. For example, if a shopper buys a cup of coffee, percentage-based tipping results in a lower tip for your staff than predefined fixed amounts.

You can override the settings defined in your Customer Area by specifying the tipping options in the payment request. This shows the new tipping options on the terminal screen during the payment flow. However, you need to implement logic in your system when to trigger the override, such as logic to offer fixed amount options instead of percentages if the total amount is low.

## Requirements

Before you begin, take into account the following requirements and preparations.

| Requirement          | Description                                                                                                                                 |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| **Integration type** | A [Terminal API](/point-of-sale/design-your-integration/terminal-api) integration with payment terminals on software version 1.97 or later. |
| **Setup steps**      | Before you begin, you need to implement logic in your system when to trigger the override.                                                  |

## Tipping options

You can present your customer with either three percentage options or three tipping amount options. Additionally, you can enable the flag to present a **Custom** tip option. The **No tip** option is always included.

## Specify tipping options in the payment request

To override the configured tipping options, in the payment request you need to include the **AskGratuity** [tender option](/point-of-sale/add-data/tender-options) and a Base64-encoded `Operation` object with the new tipping options.

Software versions 1.97 to 1.100 use an outdated `Operation` object format. Choose the correct version tab in Step 1.

1. Create an `Operation` JSON object. Select the tab for the software version that your terminal is using.

   ### Tab: Software version 1.101 and later

   Specify the following parameters:

   | Parameter    | Description                                                                                                                                                                                                                                                                                                                                                                                                                                              |
   | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
   | `Type`       | **Payment**                                                                                                                                                                                                                                                                                                                                                                                                                                              |
   | `TipOptions` | In the `TipSuggestions` object specify: - Up to three tipping options for either a fixed tipping amount (**Amount1**, **Amount2**, and **Amount3**) or a percentage of the original payment amount (**Percentage1**, **Percentage2**, and **Percentage3**). The numeric value for the percentage tipping options must not be greater than 100.
   - `TipCustom` (optional): lets the customer enter a custom tipping amount. Can be **true** or **false**.  |

   **Operation object with percentage options and TipCustom enabled**

   ```json
   {
       "Operation":[
           {
               "Type":"Payment",
               "TipOptions":{
                   "TipSuggestions":{
                   "Percentage1":15,
                   "Percentage2":18,
                   "Percentage3":20,
                   "TipCustom":true
                   }
               }
           }
       ]
   }
   ```

   ### Tab: Software version 1.97 to 1.100

   Specify the following parameters:

   | Parameter | Description                                                                                                                                                                                                                                                                                                                                                                                                                      |
   | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
   | `Type`    | **Payment**                                                                                                                                                                                                                                                                                                                                                                                                                      |
   | `Variant` | **TipSuggestions**                                                                                                                                                                                                                                                                                                                                                                                                               |
   | `Data`    | An object that contains: - Up to three tipping options for either a fixed tipping amount (**Amount1**, **Amount2**, and **Amount3**) or a percentage of the original payment amount (**Percent1**, **Percent2**, and **Percent3**). The numeric value for the percentage tipping options must not be greater than 100.
   - `TipCustom` (optional): allows shopper to place a custom tipping amount. Can be **true** or **false**.  |

   **Operation object with percentage options and custom tips enabled**

   ```json
   {
       "Operation":[
           {
               "Type":"Payment",
               "Variant":"TipSuggestions",
               "Data":{
                   "Percent1":15,
                   "Percent2":18,
                   "Percent3":20,
                   "TipCustom":true
               }
           }
       ]
   }
   ```

2. Encode the `Operation` JSON object to Base64. You will pass the resulting string in `SaleData.SaleToPOIData`. The example below shows a Base64-encoded string of the `Operation` object for software version V1.101 and later.

   **Converted to a Base64-encoded string**

   ```raw
   ewogICAgIk9wZXJhdGlvbiI6WwogICAgICAgIHsKICAgICAgICAgICAgIlR5cGUiOiJQYXltZW50IiwKICAgICAgICAgICAgIlRpcE9wdGlvbnMiOnsKICAgICAgICAgICAgICAgICJUaXBTdWdnZXN0aW9ucyI6ewogICAgICAgICAgICAgICAgICAgICJQZXJjZW50YWdlMSI6MTUsCiAgICAgICAgICAgICAgICAgICAgIlBlcmNlbnRhZ2UyIjoxOCwKICAgICAgICAgICAgICAgICAgICAiUGVyY2VudGFnZTMiOjIwLAogICAgICAgICAgICAgICAgICAgICJUaXBDdXN0b20iOnRydWUKICAgICAgICAgICAgICAgIH0KICAgICAgICAgICAgfQogICAgICAgIH0KICAgIF0KfQ==
   ```

3. [Make a payment request](/point-of-sale/basic-tapi-integration/make-a-payment#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                       | Description                                                                                                                                                                        |
     | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
     | `SaleData.SaleToAcquirerData`   | The **AskGratuity** tender option that triggers the terminal to start the tipping flow\.See [Specify tender options](/point-of-sale/add-data/tender-options/#pass-tender-options). |
     | `SaleData.SaleToPOIData`        | An object with the Base64-encoded `Operation` string that contains the new tipping options.                                                                                        |
     | `PaymentTransaction.AmountsReq` | An object with:- `Currency`: The transaction [currency](/development-resources/currency-codes).
     - `RequestedAmount`: The purchase amount, with decimals.                           |

   The example below shows how to present tipping options and initiate a transaction of **EUR 10.00**.

   **Payment request with tipping override**

   ```json
   {
     "SaleToPOIRequest":{
       "MessageHeader":{
         "ProtocolVersion":"3.0",
         "MessageClass":"Service",
         "MessageCategory":"Payment",
         "MessageType":"Request",
         "SaleID":"POSSystemID12345",
         "ServiceID":"0207111104",
         "POIID":"P400Plus-275688710"
       },
       "PaymentRequest":{
         "SaleData":{
           "SaleToAcquirerData": "tenderOption=AskGratuity",
           "SaleTransactionID":{
             "TransactionID":"27908",
             "TimeStamp":"2019-12-17T10:11:03.000Z"
           },
           "SaleToPOIData":
               "ewogICAgIk9wZXJhdGlvbiI6WwogICAgICAgIHsKICAgICAgICAgICAgIlR5cGUiOiJQYXltZW50IiwKICAgICAgICAgICAgIlRpcE9wdGlvbnMiOnsKICAgICAgICAgICAgICAgICJUaXBTdWdnZXN0aW9ucyI6ewogICAgICAgICAgICAgICAgICAgICJQZXJjZW50YWdlMSI6MTUsCiAgICAgICAgICAgICAgICAgICAgIlBlcmNlbnRhZ2UyIjoxOCwKICAgICAgICAgICAgICAgICAgICAiUGVyY2VudGFnZTMiOjIwLAogICAgICAgICAgICAgICAgICAgICJUaXBDdXN0b20iOnRydWUKICAgICAgICAgICAgICAgIH0KICAgICAgICAgICAgfQogICAgICAgIH0KICAgIF0KfQ=="
         },
         "PaymentTransaction":{
           "AmountsReq":{
             "Currency":"EUR",
             "RequestedAmount":10.00
           }
         }
       }
     }
   }
   ```

4. In the [PaymentResponse](https://docs.adyen.com/api-explorer/terminal-api/latest/post/payment#responses-200) 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`: the amount of the tip. If the customer didn't add a tip, this field is not included.
     * `AuthorizedAmount`: the total authorized amount of the transaction, consisting of the original purchase amount plus the tip amount.
     * `Currency`: the currency of the payment.

   * `Response.AdditionalResponse`: additional transaction data. Depending on [your settings](/point-of-sale/add-data/#receive-additional-data), 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 purchase 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 transaction of **EUR 10.00** with a 20 percent tip added.

   **Payment response**

   ```json
   {
      "SaleToPOIResponse":{
         "MessageHeader":{
            "MessageCategory":"Payment",
            "MessageClass":"Service",
            "MessageType":"Response",
            "POIID":"P400Plus-275688710",
            "ProtocolVersion":"3.0",
            "SaleID":"POSSystemID12345",
            "ServiceID":"775"
         },
         "PaymentResponse":{
            "POIData":{
               "POIReconciliationID":"1000",
               "POITransactionID":{
                  "TimeStamp":"2024-04-16T09:12:45.865Z",
                  "TransactionID":"gGZx001713258765025.MLJL4MVNBC3GDXT5"
               }
            },
            "PaymentReceipt":[
               "..."
            ],
            "PaymentResult":{
               "AmountsResp":{
                  "AuthorizedAmount":12.00,
                  "Currency":"EUR",
                  "TipAmount":2.00
               },
               "OnlineFlag":true,
               "PaymentAcquirerData":{...},
               "PaymentInstrumentData":{...}
            },
            "Response":{
               "AdditionalResponse":"...posAmountGratuityValue=200&posAuthAmountCurrency=EUR&posAuthAmountValue=1200&posEntryMode=CLESS_CHIP&posOriginalAmountValue=1000&posadditionalamounts.gratuityAmount=200&posadditionalamounts.originalAmountCurrency=EUR&posadditionalamounts.originalAmountValue=1000&...",
               "Result":"Success"
            },
            "SaleData":{
               "SaleTransactionID":{
                  "TimeStamp":"2024-04-16T09:12:44.892Z",
                  "TransactionID":"181"
               }
            }
         }
      }
   }
   ```

## See also

* [Tipping from the terminal](/point-of-sale/tipping/tipping-from-terminal)
* [Specify the amount to tip on](/point-of-sale/tipping/tipping-from-terminal/change-amount-to-tip-on)
* [Make a payment](/point-of-sale/basic-tapi-integration/make-a-payment)
* [Tender options](/point-of-sale/add-data/tender-options)
