---
title: "Override the amount to tip on"
description: "Specify the part of the total transaction amount that shoppers can add a tip on."
url: "https://docs.adyen.com/point-of-sale/tipping/tipping-from-terminal/change-amount-to-tip-on"
source_url: "https://docs.adyen.com/point-of-sale/tipping/tipping-from-terminal/change-amount-to-tip-on.md"
canonical: "https://docs.adyen.com/point-of-sale/tipping/tipping-from-terminal/change-amount-to-tip-on"
last_modified: "2026-06-01T15:33:14+02:00"
language: "en"
---

# Override the amount to tip on

Specify the part of the total transaction amount that shoppers can add a tip on.

[View source](/point-of-sale/tipping/tipping-from-terminal/change-amount-to-tip-on.md)

If you have defined tipping options in your Customer Area, the default behavior is that the tipping options apply to the total purchase amount. However, there are situations when you may want to let the customer add a tip to a different amount:

* When a customer buys a mix of products and services. For example, if the total amount consists of the costs of a haircut and a hair product, you can let the customer add a tip only for the cost of having the haircut.

* To exclude product-related charges, taxes, or other fees. For example, a [regulation in Quebec, Canada](https://www.assnat.qc.ca/en/travaux-parlementaires/projets-loi/projet-loi-72-43-1.html) requires tips to be calculated on pre-tax amounts. To comply with this regulation, in your payment request you can add the purchase amount before taxes as the amount to tip on.

The terminal will present the customer with the adjusted amount before adding the tip. Note that you need to implement logic in your system when to override the total purchase amount as the amount to tip on.

## 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.103 or later. |
| **Limitations**      | Tip amount overrides are currently not supported for [pay at table](/point-of-sale/pay-at-x) including split checks.                         |
| **Setup steps**      | You need to implement logic in your system when to trigger the override.                                                                     |

## Specify amount to tip on in the payment request

When you override the amount to tip on, you are automatically overriding the tipping options defined in your Customer Area as well. This means that your payment request needs to include the **AskGratuity** [tender option](/point-of-sale/add-data/tender-options) and a base-64 encoded `Operation` object with both the `AmountToTipOn` parameter and the `TipSuggestions` object.

1. Create an `Operation` JSON object with the following parameters:

   | Parameter       | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
   | --------------- |   |
   | `Type`          | **Payment**                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
   | `AmountToTipOn` | The amount that the customer can tip on.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
   | `TipOptions`    | Contains the `TipSuggestions` [object](/point-of-sale/tipping/tipping-from-terminal/override-tipping-configuration#make-a-payment-to-override-existing-tipping-options) with: - Up to three predefined tipping options for either a fixed tipping amount (**Amount1**, **Amount2**, and **Amount3**) or a percentage of the specified amount to tip on (**Percentage1**, **Percentage2**, and **Percentage3**). The numeric value for percentage tipping options must not be greater than 100.
   - `TipCustom` (optional): lets the customer enter a custom tipping amount. Value **true** or **false**.  |

   **Operation object**

   ```json
   {
       "Operation":[
           {
               "Type":"Payment",
               "TipOptions":{
                   "AmountToTipOn": 15.00,
                   "TipSuggestions":{
                       "Percentage1":15,
                       "Percentage2":18,
                       "Percentage3":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 format.

   **Converted to a Base64-encoded string**

   ```raw
    
   ```

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 the [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 tipping options.                                                                                                |
     | `PaymentTransaction.AmountsReq` | An object with:- `Currency`: The transaction [currency](/development-resources/currency-codes).
     - `RequestedAmount`: The total purchase amount, with decimals.                         |

   The example below shows how to initiate a transaction with an adjusted amount to tip on.

   **Payment request**

   ```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":
               " "
         },
         "PaymentTransaction":{
           "AmountsReq":{
             "Currency":"EUR",
             "RequestedAmount":20.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 where the original purchase amount was **EUR 20.00**, the adjusted amount to tip on was **EUR 15.00**, and a 20 percent tip was added.

   **Payment response**

   ```json
   {
       "SaleToPOIResponse":{
           "MessageHeader":{...},
           "PaymentResponse":{
               "POIData":{
                   "POIReconciliationID":"1000",
                   "POITransactionID":{
                       "TimeStamp":"2024-04-16T09:12:45.865Z",
                       "TransactionID":"u6W7001529672124004.NC6HT9CRT65ZGN82"
                   }
               },
               "PaymentReceipt":[...],
               "PaymentResult":{
                   "AmountsResp":{
                       "AuthorizedAmount":23.00,
                       "Currency":"EUR",
                       "TipAmount":3.00
                   },
                   "OnlineFlag":true,
                   "PaymentAcquirerData":{
                       "AcquirerPOIID":"V400m-324688179",
                       "AcquirerTransactionID":{
                           "TimeStamp":"2024-04-16T09:12:45.865Z",
                           "TransactionID":"NC6HT9CRT65ZGN82"
                       },
                       "ApprovalCode":"123456",
                       "MerchantID":"TestMerchantPOS"
                   },
                   "PaymentInstrumentData":{...}
               },
               "Response":{
                   "...posAmountGratuityValue=300&posAuthAmountCurrency=EUR&posAuthAmountValue=2300&posEntryMode=CLESS_CHIP&posOriginalAmountValue=2000&posadditionalamounts.gratuityAmount=300&posadditionalamounts.originalAmountCurrency=EUR&posadditionalamounts.originalAmountValue=2000&...",
                   "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)
* [Make a payment](/point-of-sale/basic-tapi-integration/make-a-payment)
* [Override tipping options](/point-of-sale/tipping/tipping-from-terminal/override-tipping-configuration)
* [Tender options](/point-of-sale/add-data/tender-options)
* [Set up tipping on standalone](/point-of-sale/standalone/standalone-build/set-up-standalone)
