---
title: "Tipping"
description: "Implement tipping (gratuity) in your payment flow."
url: "https://docs.adyen.com/platforms/in-person-payments/tipping"
source_url: "https://docs.adyen.com/platforms/in-person-payments/tipping.md"
canonical: "https://docs.adyen.com/platforms/in-person-payments/tipping"
last_modified: "2023-05-03T17:04:00+02:00"
language: "en"
---

# Tipping

Implement tipping (gratuity) in your payment flow.

[View source](/platforms/in-person-payments/tipping.md)

When a customer adds a tip (gratuity) to their payment, it is booked to your liable account by default. However, you can book the entire tip amount directly to your user's balance account by providing an additional split item in the payment request.

You can book the tip to your user's balance account when you use one of the following tipping methods:

* [Tipping from the POS app](/point-of-sale/tipping/tipping-from-cash-register/)
* [Tipping from the terminal](/point-of-sale/tipping/tipping-from-terminal/)

## Requirements

In addition to the [general requirements](/platforms/in-person-payments#requirements) for in-person payments with an Adyen for Platforms integration, take into account the following information.

| Requirement          | Description                                                                                                                                                                                                                                                                                                                              |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Integration type** | A [Terminal API](/point-of-sale/design-your-integration/terminal-api) integration with [payment terminals](/point-of-sale/what-we-support/select-your-terminals) or with a [Mobile solution](/point-of-sale/ipp-mobile).The standalone solution does not support adding split instructions to individual payment authorization requests. |
| **Limitations**      | Booking the tip to your user's balance account is not supported with [tipping on the receipt](/point-of-sale/tipping/tipping-on-receipt).                                                                                                                                                                                                |
| **Setup steps**      | Check the flow, the requirements, and the setup or configuration steps for your chosen tipping method: [tipping from the POS app](/point-of-sale/tipping/tipping-from-cash-register/) or [tipping from the terminal](/point-of-sale/tipping/tipping-from-terminal/).                                                                     |

## Tip from POS app and book to your user

To make payment request that adds a tip and split instructions for how to book the tip when you use tipping from the POS app:

1. When you [gather the split instructions for the payment](/platforms/in-person-payments/split-transactions/split-payments-at-authorization#gather-data), add a split item for the tip:

   * Increase the `split.nrOfItems` by one, to accommodate the tip split item you are adding.

   * In the split item for the tip, specify:

     | Key                                   | Description                                                                                                                                                               |
     | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
     | `split.item[ITEM_NUMBER].type`        | The type of split. Set this to **Tip**.                                                                                                                                   |
     | `split.item[ITEM_NUMBER].account`     | The account that will receive the tip. This is the `balanceAccountID` of one of your user's balance accounts. You cannot split the tip between multiple balance accounts. |
     | `split.item[ITEM_NUMBER].reference`   | Your reference for the tip, reflected in the [Balance Platform Accounting Report](/platforms/reports-and-fees/balance-platform-accounting-report).                        |
     | `split.item[ITEM_NUMBER].description` | Your description of the tip, reflected in the [Balance Platform Accounting Report](/platforms/reports-and-fees/balance-platform-accounting-report).                       |

   Do not include the tip amount in the `split.totalAmount` field and do not add a `split.item[ITEM_NUMBER].amount` field for the tip.

2. Format the split instructions in one of the following ways:

   * **Option 1**: as a string of form-encoded key-value pairs (using **&** as a separator).
   * **Option 2**: as a JSON object converted to a Base64-encoded string.

   As an example, we use a payment of USD 630.00 that is split into:

   * USD 600.00 to be paid to your user's first balance account as the sale amount.
   * USD 20.00 to be paid to your liable account as your platform's commission.
   * The payment fee to be booked to your user's first balance account. This will be deducted from the sale amount.
   * USD 10.00 to be paid to your user's second balance account as the tip.

   In this case, the `split.nrOfItems` is **4** and the `split.totalAmount` is **62000**, because the payment fee is not known yet, and the tip amount should not be added even if you do know it in advance.

   ### Tab: Key-value pairs

   1. Turn the split instructions you gathered into key-value pairs.

      **Split tip instructions as key-value pairs**

      ```raw
      split.api=1
      split.nrOfItems=4
      split.totalAmount=62000
      split.currencyCode=USD
      split.item1.amount=60000
      split.item1.type=BalanceAccount
      split.item1.account=BA00000000000000000000001
      split.item1.reference=Your reference for the sale
      split.item1.description=Your description for the sale
      split.item2.amount=2000
      split.item2.type=Commission
      split.item2.reference=Your reference for your commission
      split.item2.description=Your description for your commission
      split.item3.type=PaymentFee
      split.item3.account=BA00000000000000000000001
      split.item3.reference=Your reference for the payment fee
      split.item3.description=Your description for the payment fee
      split.item4.type=Tip
      split.item4.account=BA00000000000000000000002
      split.item4.reference=Your reference for the tip
      split.item4.description=Your description for the tip
      ```

   2. Concatenate the key-value pairs into a string by separating them with ampersands (**&**).

      **Concatenated key-value pairs**

      ```bash
      split.api=1&split.nrOfItems=4&split.totalAmount=62000&split.currencyCode=USD&split.item1.amount=60000&split.item1.type=BalanceAccount&split.item1.account=BA00000000000000000000001&split.item1.reference=Your reference for the sale&split.item1.description=Your description for the sale&split.item2.amount=2000&split.item2.type=Commission&split.item2.reference=Your reference for your commission&split.item2.description=Your description for your commission&split.item3.type=PaymentFee&split.item3.account=BA00000000000000000000001&split.item3.reference=Your reference for the payment fee&split.item3.description=Your description for the payment fee&split.item4.type=Tip&split.item4.account=BA00000000000000000000002&split.item4.reference=Your reference for the tip&split.item4.description=Your description for the tip
      ```

   ### Tab: Base64-encoded JSON

   1. Create a JSON object consisting of an `additionalData` object containing the split instructions you gathered.

      **JSON object**

      ```json
      {
         "additionalData": {
             "split.api": "1",
             "split.nrOfItems": "4",
             "split.totalAmount": "62000",
             "split.currencyCode": "USD",
             "split.item1.amount": "60000",
             "split.item1.type": "BalanceAccount",
             "split.item1.account": "BA00000000000000000000001",
             "split.item1.reference": "Your reference for the sale",
             "split.item1.description": "Your description for the sale",
             "split.item2.amount": "2000",
             "split.item2.type": "Commission",
             "split.item2.reference": "Your reference for your commission",
             "split.item2.description": "Your description for your commission",
             "split.item3.type": "PaymentFee",
             "split.item3.account": "BA00000000000000000000001",
             "split.item3.reference": "Your reference for the payment fee",
             "split.item3.description": "Your description for the payment fee",
             "split.item4.type": "Tip",
             "split.item4.account": "BA00000000000000000000002",
             "split.item4.reference": "Your reference for the tip",
             "split.item4.description": "Your description for the tip"
         }
      }
      ```

   2. Encode the JSON object to Base64.

      **Base64 string**

      ```bash
       
      ```

3. [Make a Terminal API payment request](/platforms/in-person-payments/split-transactions/split-payments-at-authorization), including:

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

     | Parameter                                       | Required                                                                                    | Description                                                        |
     | ----------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ |
     | `SaleData.SaleToAcquirerData`                   | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The formatted string of split instructions for the payment.        |
     | `PaymentTransaction.AmountsReq.Currency`        | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The transaction [currency](/development-resources/currency-codes). |
     | `PaymentTransaction.AmountsReq.RequestedAmount` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The transaction amount.                                            |
     | `PaymentTransaction.AmountsReq.TipAmount`       | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The tip amount.                                                    |

   **Tipping from the POS app with split instructions as key-value pairs**

   ```json
   {
       "SaleToPOIRequest": {
           "MessageHeader": {
               "ProtocolVersion": "3.0",
               "MessageClass": "Service",
               "MessageCategory": "Payment",
               "MessageType": "Request",
               "SaleID": "POSSystemID12345",
               "ServiceID": "0207111104",
               "POIID": "V400m-324688179"
           },
           "PaymentRequest": {
               "SaleData": {
                   "SaleTransactionID": {
                       "TransactionID": "27908",
                       "TimeStamp": "2025-10-28T10:11:04+00:00"
                   },
                   "SaleToAcquirerData": "split.api=1&split.nrOfItems=4&split.totalAmount=62000&split.currencyCode=USD&split.item1.amount=60000&split.item1.type=BalanceAccount&split.item1.account=BA00000000000000000000001&split.item1.reference=Your reference for the sale&split.item1.description=Your description for the sale&split.item2.amount=2000&split.item2.type=Commission&split.item2.reference=Your reference for your commission&split.item2.description=Your description for your commission&split.item3.type=PaymentFee&split.item3.account=BA00000000000000000000001&split.item3.reference=Your reference for the payment fee&split.item3.description=Your description for the payment fee&split.item4.type=Tip&split.item4.account=BA00000000000000000000002&split.item4.reference=Your reference for the tip&split.item4.description=Your description for the tip"
               },
               "PaymentTransaction": {
                   "AmountsReq": {
                       "Currency": "USD",
                       "RequestedAmount": 620.00
                       "TipAmount": 10.00
                   }
               }
           }
       }
   }
   ```

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

   * `PaymentResult.AmountsResp`:

     * `TipAmount`: The amount of the tip. If the customer declined adding a tip, this field is not included.
     * `AuthorizedAmount`: The total amount of the payment (original transaction amount plus tip amount).
     * `Currency`: The currency of the payment.

   * `Response.AdditionalResponse`:

     * `posadditionalamounts.originalAmountValue`: The original transaction amount in [minor units](/development-resources/currency-codes).
     * `posAmountGratuityValue`: The tip amount in minor units.
     * `authorisedAmountValue`: The total authorised amount in minor units.

   **Response**

   ```json
   {
      "SaleToPOIResponse": {
        "MessageHeader": {...},
        "PaymentResponse": {
          "POIData": {...},
          "PaymentReceipt": [...],
          "PaymentResult": {
            "AmountsResp": {
              "AuthorizedAmount": 630,
              "Currency": "USD",
              "TipAmount": 10
            },
            ...,
            "PaymentInstrumentData": {...}
          },
          "Response": {
            "AdditionalResponse": "...gratuityAmount=1000&posAmountGratuityValue=1000&posAuthAmountCurrency=USD&posAuthAmountValue=63000&posOriginalAmountValue=62000&posadditionalamounts.gratuityAmount=1000&posadditionalamounts.originalAmountCurrency=USD&posadditionalamounts.originalAmountValue=62000...",
            "Result": "Success"
          },
          "SaleData": {
            "SaleTransactionID": {...}
          }
        }
      }
   }
   ```

## Tip from terminal and book to your user

To make payment request that adds a tip and split instructions for how to book the tip when you use tipping from the terminal:

1. When you [gather the split instructions for the payment](/platforms/in-person-payments/split-transactions/split-payments-at-authorization#gather-data), add a split item for the tip:

   * Increase the `split.nrOfItems` by one, to accommodate the tip split item you are adding.

   * In the split item for the tip, specify:

     | Key                                   | Description                                                                                                                                                               |
     | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
     | `split.item[ITEM_NUMBER].type`        | The type of split. Set this to **Tip**.                                                                                                                                   |
     | `split.item[ITEM_NUMBER].account`     | The account that will receive the tip. This is the `balanceAccountID` of one of your user's balance accounts. You cannot split the tip between multiple balance accounts. |
     | `split.item[ITEM_NUMBER].reference`   | Your reference for the tip, reflected in the [Balance Platform Accounting Report](/platforms/reports-and-fees/balance-platform-accounting-report).                        |
     | `split.item[ITEM_NUMBER].description` | Your description of the tip, reflected in the [Balance Platform Accounting Report](/platforms/reports-and-fees/balance-platform-accounting-report).                       |

   Do not include the tip amount in the `split.totalAmount` field and do not add a `split.item[ITEM_NUMBER].amount` field for the tip.

2. Format the split instructions in one of the following ways:

   * **Option 1**: as a string of form-encoded key-value pairs (using **&** as a separator).
   * **Option 2**: as a JSON object converted to a Base64-encoded string.

   As an example, we use a payment of USD 630.00 that is split into:

   * USD 600.00 to be paid to your user's first balance account as the sale amount.
   * USD 20.00 to be paid to your liable account as your platform's commission.
   * The payment fee to be booked to your user's first balance account. This will be deducted from the sale amount.
   * The tip amount to be paid to your user's second balance account.

   In this case, the `split.nrOfItems` is **4** and the `split.totalAmount` is **62000** because the payment fee and the tip amount are not known yet.

   ### Tab: Key-value pairs

   1. Turn the split instructions you gathered into key-value pairs, and add a `tenderOption` parameter set to **AskGratuity**.

      **Split tip instructions as key-value pairs**

      ```raw
      tenderOption=AskGratuity
      split.api=1
      split.nrOfItems=4
      split.totalAmount=62000
      split.currencyCode=USD
      split.item1.amount=60000
      split.item1.type=BalanceAccount
      split.item1.account=BA00000000000000000000001
      split.item1.reference=Your reference for the sale
      split.item1.description=Your description for the sale
      split.item2.amount=2000
      split.item2.type=Commission
      split.item2.reference=Your reference for your commission
      split.item2.description=Your description for your commission
      split.item3.type=PaymentFee
      split.item3.account=BA00000000000000000000001
      split.item3.reference=Your reference for the payment fee
      split.item3.description=Your description for the payment fee
      split.item4.type=Tip
      split.item4.account=BA00000000000000000000002
      split.item4.reference=Your reference for the tip
      split.item4.description=Your description for the tip
      ```

   2. Concatenate the key-value pairs into a string by separating them with ampersands (**&**).

      **Concatenated key-value pairs**

      ```bash
      tenderOption=AskGratuity&split.api=1&split.nrOfItems=4&split.totalAmount=62000&split.currencyCode=USD&split.item1.amount=60000&split.item1.type=BalanceAccount&split.item1.account=BA00000000000000000000001&split.item1.reference=Your reference for the sale&split.item1.description=Your description for the sale&split.item2.amount=2000&split.item2.type=Commission&split.item2.reference=Your reference for your commission&split.item2.description=Your description for your commission&split.item3.type=PaymentFee&split.item3.account=BA00000000000000000000001&split.item3.reference=Your reference for the payment fee&split.item3.description=Your description for the payment fee&split.item4.type=Tip&split.item4.account=BA00000000000000000000002&split.item4.reference=Your reference for the tip&split.item4.description=Your description for the tip
      ```

   ### Tab: Base64-encoded JSON

   1. Create a JSON object consisting of an `additionalData` object containing the `tenderOption` parameter set to **AskGratuity**, and the split instructions you gathered.

      **JSON object**

      ```json
      {
         "tenderOption": "AskGratuity",
         "additionalData": {
             "split.api": "1",
             "split.nrOfItems": "4",
             "split.totalAmount": "62000",
             "split.currencyCode": "USD",
             "split.item1.amount": "60000",
             "split.item1.type": "BalanceAccount",
             "split.item1.account": "BA00000000000000000000001",
             "split.item1.reference": "Your reference for the sale",
             "split.item1.description": "Your description for the sale",
             "split.item2.amount": "2000",
             "split.item2.type": "Commission",
             "split.item2.reference": "Your reference for your commission",
             "split.item2.description": "Your description for your commission",
             "split.item3.type": "PaymentFee",
             "split.item3.account": "BA00000000000000000000001",
             "split.item3.reference": "Your reference for the payment fee",
             "split.item3.description": "Your description for the payment fee",
             "split.item4.type": "Tip",
             "split.item4.account": "BA00000000000000000000002",
             "split.item4.reference": "Your reference for the tip",
             "split.item4.description": "Your description for the tip"
         }
      }
      ```

   2. Encode the JSON object to Base64.

      **Base64 string**

      ```bash
       
      ```

3. [Make a Terminal API payment request](/platforms/in-person-payments/split-transactions/split-payments-at-authorization), including:

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

     | Parameter                                       | Required                                                                                    | Description                                                                                                                                                                  |
     | ----------------------------------------------- | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
     | `SaleData.SaleToAcquirerData`                   | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The **AskGratuity** tender option and the split instructions, provided as a string of concatenated key-value pairs or as a JSON object converted to a Base64-encoded string. |
     | `PaymentTransaction.AmountsReq.Currency`        | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The transaction [currency](/development-resources/currency-codes).                                                                                                           |
     | `PaymentTransaction.AmountsReq.RequestedAmount` | ![-white\_check\_mark-](/user/data/smileys/emoji/white_check_mark.png "-white_check_mark-") | The transaction amount.                                                                                                                                                      |

     **Tipping from the terminal with split instructions as key-value pairs**

     ```json
     {
         "SaleToPOIRequest": {
             "MessageHeader": {
                 "ProtocolVersion": "3.0",
                 "MessageClass": "Service",
                 "MessageCategory": "Payment",
                 "MessageType": "Request",
                 "SaleID": "POSSystemID12345",
                 "ServiceID": "0207111104",
                 "POIID": "V400m-324688179"
             },
             "PaymentRequest": {
                 "SaleData": {
                     "SaleTransactionID": {
                         "TransactionID": "27908",
                         "TimeStamp": "2022-10-28T10:11:04+00:00"
                     },
                     "SaleToAcquirerData": "tenderOption=AskGratuity&split.api=1&split.nrOfItems=3&split.totalAmount=62000&split.currencyCode=USD&split.item1.amount=60000&split.item1.type=BalanceAccount&split.item1.account=BA00000000000000000000001&split.item1.reference=reference_split_1&split.item1.description=description_split_1&split.item2.amount=2000&split.item2.type=Commission&split.item2.reference=reference_commission&split.item2.description=description_commission&split.item3.type=Tip&split.item3.account=BA00000000000000000000001&split.item3.reference=reference_tip&split.item3.description=description_tip&split.item4.type=PaymentFee&split.item4.account=BA00000000000000000000002&split.item4.reference=reference_fees&split.item4.description=description_fees"
                 },
                 "PaymentTransaction": {
                     "AmountsReq": {
                         "Currency": "USD",
                         "RequestedAmount": 620.00
                     }
                 }
             }
         }
     }
     ```

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

   * `PaymentResult.AmountsResp`:

     * `TipAmount`: The amount of the tip. If the customer declined adding a tip, this field is not included.
     * `AuthorizedAmount`: The total amount of the payment (original transaction amount plus tip amount).
     * `Currency`: The currency of the payment.

   * `Response.AdditionalResponse`:

     * `posadditionalamounts.originalAmountValue`: The original transaction amount in [minor units](/development-resources/currency-codes).
     * `posAmountGratuityValue`: The tip amount in minor units.
     * `authorisedAmountValue`: The total authorised amount in minor units.

   **Response**

   ```json
   {
      "SaleToPOIResponse": {
        "MessageHeader": {...},
        "PaymentResponse": {
          "POIData": {...},
          "PaymentReceipt": [...],
          "PaymentResult": {
            "AmountsResp": {
              "AuthorizedAmount": 630,
              "Currency": "USD",
              "TipAmount": 10
            },
            ...,
            "PaymentInstrumentData": {...}
          },
          "Response": {
            "AdditionalResponse": "...gratuityAmount=1000&posAmountGratuityValue=1000&posAuthAmountCurrency=USD&posAuthAmountValue=63000&posOriginalAmountValue=62000&posadditionalamounts.gratuityAmount=1000&posadditionalamounts.originalAmountCurrency=USD&posadditionalamounts.originalAmountValue=62000...",
            "Result": "Success"
          },
          "SaleData": {
            "SaleTransactionID": {...}
          }
        }
      }
   }
   ```

## See also

* [Tipping](/point-of-sale/tipping/)
