{"title":"Tipping from the terminal","category":"default","creationDate":1681721040,"content":"<p>This page describes how to set up and use tipping options for your customers on Adyen payment terminals. Depending on what is customary in your region, there are various ways to let the payment terminal ask your customers to add a tip:<\/p>\n<ul>\n<li><a href=\"#direct-tipping\">Ask for a tip amount<\/a>: the customer chooses a predefined tipping option on the display or enters a custom tip amount (or chooses to skip giving a tip).<\/li>\n<li><a href=\"#indirect-tipping\">Ask for a total amount<\/a>: if the customer wants to give a tip, they enter a total amount that is higher than the original purchase amount. This is customary in Nordic countries\/regions.<\/li>\n<\/ul>\n<p>The <a href=\"#payment-tipping-terminal\">payment request<\/a> to trigger tipping, is the same in both cases.<\/p>\n<h2>Requirements<\/h2>\n<p>Before you begin, take into account the following requirements, limitations, and preparations.<\/p>\n<table>\n<thead>\n<tr>\n<th style=\"text-align: left;\">Requirement<\/th>\n<th style=\"text-align: left;\">Description<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td style=\"text-align: left;\"><strong>Integration type<\/strong><\/td>\n<td style=\"text-align: left;\"><a href=\"\/point-of-sale\/design-your-integration\/terminal-api\">Terminal API<\/a> integration with Adyen-provided payment terminals.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><strong>Webhooks<\/strong><\/td>\n<td style=\"text-align: left;\">Set up <a href=\"\/development-resources\/webhooks\/\">standard webhooks<\/a> and optionally <a href=\"\/point-of-sale\/design-your-integration\/notifications\/display-notifications\">display notifications<\/a> to keep your staff informed.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><strong>Hardware<\/strong><\/td>\n<td style=\"text-align: left;\">All terminal models are supported, except unattended terminals.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><strong>Setup steps<\/strong><\/td>\n<td style=\"text-align: left;\">Before you begin: <ul><li markdown=\"1\">If you want to prompt for a tip <a href=\"#tipping-options-after\">after card entry<\/a> instead of before, ask our <a href=\"https:\/\/ca-test.adyen.com\/ca\/ca\/contactUs\/support.shtml?form=other\" target=\"_blank\" rel=\"nofollow noopener noreferrer\" class=\"external-link no-image\">Support Team<\/a> to enable that, and to enable single tap.<\/li> <li markdown=\"1\">If you want to prompt for a <a href=\"#indirect-tipping\">total amount<\/a> instead of a tip amount, ask our <a href=\"https:\/\/ca-test.adyen.com\/ca\/ca\/contactUs\/support.shtml?form=other\" target=\"_blank\" rel=\"nofollow noopener noreferrer\" class=\"external-link no-image\">Support Team<\/a> to enable that.<\/li><\/ul><\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<h2 id=\"direct-tipping\">Ask for a tip amount<\/h2>\n<p>You can <a href=\"#define-tipping-options\">configure tipping<\/a> options either from the Customer Area or with the Management API. Customers can then choose one of the predefined tipping options or enter a custom tip amount. Asking for a tip can appear before or after the customer enters their card. The default is tipping before card entry.<\/p>\n<h3 id=\"tipping-options-before\">Before card entry<\/h3>\n<p>The terminal shows the purchase amount plus the tipping prompt or options you configured, and waits for the customer to respond. Then the terminal asks the customer to present their card and, if required, complete the payment by providing their PIN or signature.<br \/>\nNo configuration from our side is needed for this.<\/p>\n<p>To ask for a tip before card entry:<\/p>\n<ol>\n<li><a href=\"#define-tipping-options\">Configure tipping options<\/a> in your Customer Area or with Management API.<\/li>\n<li><a href=\"#payment-tipping-terminal\">Make payment requests<\/a> using the tender option <span translate=\"no\"><strong>AskGratuity<\/strong><\/span>.<\/li>\n<\/ol>\n<h3 id=\"tipping-options-after\">After card entry<\/h3>\n<p>The terminal shows the purchase amount and asks the customer to present their card. Then the terminal shows the tipping prompt or options you configured, and waits for the customer to respond. If required, the terminal asks the customer to complete the payment by providing their PIN or signature.<\/p>\n<p>To ask for a tip after card entry:<\/p>\n<ol>\n<li>Contact our <a href=\"https:\/\/ca-test.adyen.com\/ca\/ca\/contactUs\/support.shtml?form=other\" target=\"_blank\" rel=\"nofollow noopener noreferrer\" class=\"external-link no-image\">Support Team<\/a> and ask them to:\n<ul>\n<li>Enable tipping options after card entry.<\/li>\n<li>Optionally, enable single tap. For contactless transactions, this ensures the terminal does not ask the customer to tap their card again after selecting a tip.<\/li>\n<\/ul><\/li>\n<li><a href=\"#define-tipping-options\">Configure tipping options<\/a> in your Customer Area or with Management API.<\/li>\n<li><a href=\"#payment-tipping-terminal\">Make payment requests<\/a> using the tender option <span translate=\"no\"><strong>AskGratuity<\/strong><\/span>.<\/li>\n<\/ol>\n<h3 id=\"define-tipping-options\">Configure tipping options<\/h3>\n<p>It is possible to ask for a tip without tipping options. The payment terminal then shows a prompt to enter a tip plus an option for not giving a tip. To give a tip, the customer enters the amount and confirms.<\/p>\n<p>To make tipping easier for your customers, you can define tipping options that your customer can select on the terminal. The options can be any combination of percentages, calculated amounts, and a custom amount. You can configure the terminal to show only the percentage, the percentage and the calculated total amount together and only the fixed tip amount.<\/p>\n<table>\n<thead>\n<tr>\n<th style=\"text-align: left;\"><\/th>\n<th style=\"text-align: left;\"><\/th>\n<th style=\"text-align: left;\"><\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td style=\"text-align: left;\">Tipping without options: <br> <img title=\"Tipping prompt\" alt=\"\" src=\"\/images\/f\/1\/5\/7\/7\/f1577eef16227d16757763dbb22fbaaba0c8a3e6-screen-entipping-enter-tip-amount.png\" \/><\/td>\n<td style=\"text-align: left;\">Tipping with percentage options: <br> <img title=\"Tipping options\" alt=\"\" src=\"\/images\/c\/2\/6\/e\/b\/c26ebd9fac46aa2761e05ce06deb6ff4240b294b-screen-entipping-predefined-options-portrait.png\" \/><\/td>\n<td style=\"text-align: left;\">Percentage and calculated tip amounts: <br> <img title=\"Both predefined tipping options\" alt=\"\" src=\"\/images\/5\/7\/e\/8\/7\/57e87d103ad8f491db83d39be546782dace453df-screen-entipping-percentage-and-totals.png\" \/><\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<p>You can configure tipping either from your Customer Area or by using the Management API.<\/p>\n\n<div id=\"tab6Kgma\">\n    <div data-component-wrapper=\"tabs\">\n        <tabs\n                        :items=\"[{&quot;title&quot;:&quot;Customer Area&quot;,&quot;content&quot;:&quot;\\n&lt;p&gt;To configure asking for a tip amount from your Customer Area:&lt;\\\/p&gt;\\n&lt;ol&gt;\\n&lt;li&gt;\\n&lt;p&gt;Log in to your &lt;a href=\\&quot;https:\\\/\\\/ca-test.adyen.com\\\/\\&quot; target=\\&quot;_blank\\&quot; rel=\\&quot;nofollow noopener noreferrer\\&quot; class=\\&quot;external-link no-image\\&quot;&gt;Customer Area&lt;\\\/a&gt;.&lt;\\\/p&gt;\\n&lt;\\\/li&gt;\\n&lt;li&gt;\\n&lt;p&gt;Optionally, switch to the merchant account, store, or terminal that you want to configure tipping for.&lt;\\\/p&gt;\\n&lt;\\\/li&gt;\\n&lt;li&gt;\\n&lt;p&gt;Go to &lt;strong&gt;In-person payments&lt;\\\/strong&gt; &amp;gt; &lt;strong&gt;Terminal settings&lt;\\\/strong&gt;.&lt;\\\/p&gt;\\n&lt;\\\/li&gt;\\n&lt;li&gt;\\n&lt;p&gt;Go to &lt;strong&gt;Payment features&lt;\\\/strong&gt; &amp;gt; &lt;strong&gt;Tipping&lt;\\\/strong&gt;.&lt;\\\/p&gt;\\n&lt;\\\/li&gt;\\n&lt;li&gt;\\n&lt;p&gt;At &lt;strong&gt;Enable tipping&lt;\\\/strong&gt;, select &lt;strong&gt;Enabled&lt;\\\/strong&gt;.&lt;\\\/p&gt;\\n&lt;\\\/li&gt;\\n&lt;li&gt;\\n&lt;p&gt;Select the &lt;strong&gt;Currency&lt;\\\/strong&gt; that the settings should apply to.&lt;\\\/p&gt;\\n&lt;\\\/li&gt;\\n&lt;li&gt;\\n&lt;p&gt;Decide if you want to let shopper enter a tip or show one of the predefined options.&lt;\\\/p&gt;\\n&lt;\\\/li&gt;\\n&lt;li&gt;\\n&lt;p&gt;If you want to let shopper enter a tip, at &lt;strong&gt;Type of tipping&lt;\\\/strong&gt;, select &lt;strong&gt;Shopper enters tip amount&lt;\\\/strong&gt; to show the screen for tipping without options.&lt;\\\/p&gt;\\n&lt;\\\/li&gt;\\n&lt;li&gt;\\n&lt;p&gt;If you want to show one of the predefined options:&lt;\\\/p&gt;\\n&lt;ol&gt;\\n&lt;li&gt;At &lt;strong&gt;Type of tipping&lt;\\\/strong&gt;, select &lt;strong&gt;Shopper selects a predefined option&lt;\\\/strong&gt; to show the screen with predefined tipping options.&lt;\\\/li&gt;\\n&lt;li&gt;Define the options:\\n&lt;ul&gt;\\n&lt;li&gt;You can define different options for different currencies, except at store or terminal level where only one currency applies.&lt;\\\/li&gt;\\n&lt;li&gt;Per currency, you can define a maximum of four options. We automatically add an option for not giving a tip.&lt;\\\/li&gt;\\n&lt;li&gt;An option can be for a specific &lt;strong&gt;amount&lt;\\\/strong&gt;, for a &lt;strong&gt;percentage&lt;\\\/strong&gt; of the purchase, or for a &lt;strong&gt;custom&lt;\\\/strong&gt; tip (this leads the customer to a screen where they can enter a tip amount).&lt;\\\/li&gt;\\n&lt;li&gt;Optionally, enable &lt;strong&gt;Show calculated percentage amount&lt;\\\/strong&gt; to show the amount associated with the &lt;strong&gt;percentage&lt;\\\/strong&gt; tipping options.&lt;\\\/li&gt;\\n&lt;\\\/ul&gt;&lt;\\\/li&gt;\\n&lt;\\\/ol&gt;\\n&lt;\\\/li&gt;\\n&lt;li&gt;\\n&lt;p&gt;If applicable, select &lt;strong&gt;Add another currency&lt;\\\/strong&gt;, select a currency, and configure tipping for that currency.&lt;\\\/p&gt;\\n&lt;\\\/li&gt;\\n&lt;li&gt;\\n&lt;p&gt;Select &lt;strong&gt;Save&lt;\\\/strong&gt;.&lt;\\\/p&gt;\\n&lt;\\\/li&gt;\\n&lt;\\\/ol&gt;\\n&lt;p&gt;You can configure your POS app to &lt;a href=\\&quot;\\\/point-of-sale\\\/tipping\\\/tipping-from-terminal\\\/override-tipping-configuration\\&quot;&gt;override the tipping settings&lt;\\\/a&gt; that you have defined in your Customer Area.&lt;\\\/p&gt;\\n&quot;,&quot;altTitle&quot;:&quot;set-up-ca-3&quot;,&quot;oldTabId&quot;:1,&quot;relation&quot;:&quot;&quot;},{&quot;title&quot;:&quot;API&quot;,&quot;content&quot;:&quot;\\n&lt;p&gt;To configure tipping with Management API:&lt;\\\/p&gt;\\n&lt;ol&gt;\\n&lt;li&gt;\\n&lt;p&gt;Make a PATCH request to the &lt;code&gt;\\\/terminalSettings&lt;\\\/code&gt; endpoint for the company account, merchant account, store, or terminal, specifying the &lt;code&gt;gratuities&lt;\\\/code&gt; object.&lt;\\\/p&gt;\\n&lt;p&gt;Use one of the following endpoints:&lt;\\\/p&gt;\\n&lt;ul&gt;\\n&lt;li&gt;\\n &lt;a href=\\&quot;https:\\\/\\\/docs.adyen.com\\\/api-explorer\\\/Management\\\/latest\\\/patch\\\/companies\\\/(companyId)\\\/terminalSettings\\&quot; class=\\&quot;codeLabel  external-link no-image\\&quot; target=\\&quot;_blank\\&quot; rel=\\&quot;nofollow noopener noreferrer\\&quot;&gt;\\\/companies\\\/{companyId}\\\/terminalSettings&lt;\\\/a&gt;\\n&lt;\\\/li&gt;\\n&lt;li&gt;\\n &lt;a href=\\&quot;https:\\\/\\\/docs.adyen.com\\\/api-explorer\\\/Management\\\/latest\\\/patch\\\/merchants\\\/(merchantId)\\\/terminalSettings\\&quot; class=\\&quot;codeLabel  external-link no-image\\&quot; target=\\&quot;_blank\\&quot; rel=\\&quot;nofollow noopener noreferrer\\&quot;&gt;\\\/merchants\\\/{merchantId}\\\/terminalSettings&lt;\\\/a&gt;\\n&lt;\\\/li&gt;\\n&lt;li&gt;\\n &lt;a href=\\&quot;https:\\\/\\\/docs.adyen.com\\\/api-explorer\\\/Management\\\/latest\\\/patch\\\/stores\\\/(storeId)\\\/terminalSettings\\&quot; class=\\&quot;codeLabel  external-link no-image\\&quot; target=\\&quot;_blank\\&quot; rel=\\&quot;nofollow noopener noreferrer\\&quot;&gt;\\\/stores\\\/{storeId}\\\/terminalSettings&lt;\\\/a&gt;\\n&lt;\\\/li&gt;\\n&lt;li&gt;\\n &lt;a href=\\&quot;https:\\\/\\\/docs.adyen.com\\\/api-explorer\\\/Management\\\/latest\\\/patch\\\/terminals\\\/(terminalId)\\\/terminalSettings\\&quot; class=\\&quot;codeLabel  external-link no-image\\&quot; target=\\&quot;_blank\\&quot; rel=\\&quot;nofollow noopener noreferrer\\&quot;&gt;\\\/terminals\\\/{terminalId}\\\/terminalSettings&lt;\\\/a&gt;\\n&lt;\\\/li&gt;\\n&lt;\\\/ul&gt;\\n&lt;p&gt;In the request body, specify a  &lt;a href=\\&quot;https:\\\/\\\/docs.adyen.com\\\/api-explorer\\\/Management\\\/latest\\\/patch\\\/companies\\\/(companyId)\\\/terminalSettings#request-gratuities\\&quot; class=\\&quot;codeLabel  external-link no-image\\&quot; target=\\&quot;_blank\\&quot; rel=\\&quot;nofollow noopener noreferrer\\&quot;&gt;gratuities&lt;\\\/a&gt; object with the following parameters:&lt;\\\/p&gt;\\n&lt;table&gt;\\n&lt;thead&gt;\\n&lt;tr&gt;\\n&lt;th style=\\&quot;text-align: left;\\&quot;&gt;Parameter&lt;\\\/th&gt;\\n&lt;th style=\\&quot;text-align: left;\\&quot;&gt;Required&lt;\\\/th&gt;\\n&lt;th style=\\&quot;text-align: left;\\&quot;&gt;Type&lt;\\\/th&gt;\\n&lt;th style=\\&quot;text-align: left;\\&quot;&gt;Description&lt;\\\/th&gt;\\n&lt;\\\/tr&gt;\\n&lt;\\\/thead&gt;\\n&lt;tbody&gt;\\n&lt;tr&gt;\\n&lt;td style=\\&quot;text-align: left;\\&quot;&gt; &lt;a href=\\&quot;https:\\\/\\\/docs.adyen.com\\\/api-explorer\\\/Management\\\/latest\\\/patch\\\/companies\\\/(companyId)\\\/terminalSettings#request-gratuities-currency\\&quot; class=\\&quot;codeLabel  external-link no-image\\&quot; target=\\&quot;_blank\\&quot; rel=\\&quot;nofollow noopener noreferrer\\&quot;&gt;currency&lt;\\\/a&gt;&lt;\\\/td&gt;\\n&lt;td style=\\&quot;text-align: left;\\&quot;&gt;&lt;img title=\\&quot;-white_check_mark-\\&quot; alt=\\&quot;-white_check_mark-\\&quot; class=\\&quot;smileys\\&quot; src=\\&quot;\\\/user\\\/data\\\/smileys\\\/emoji\\\/white_check_mark.png\\&quot; \\\/&gt;&lt;\\\/td&gt;\\n&lt;td style=\\&quot;text-align: left;\\&quot;&gt;string&lt;\\\/td&gt;\\n&lt;td style=\\&quot;text-align: left;\\&quot;&gt;The currency that the tipping settings apply to.&lt;\\\/td&gt;\\n&lt;\\\/tr&gt;\\n&lt;tr&gt;\\n&lt;td style=\\&quot;text-align: left;\\&quot;&gt; &lt;a href=\\&quot;https:\\\/\\\/docs.adyen.com\\\/api-explorer\\\/Management\\\/latest\\\/patch\\\/companies\\\/(companyId)\\\/terminalSettings#request-gratuities-usePredefinedTipEntries\\&quot; class=\\&quot;codeLabel  external-link no-image\\&quot; target=\\&quot;_blank\\&quot; rel=\\&quot;nofollow noopener noreferrer\\&quot;&gt;usePredefinedTipEntries&lt;\\\/a&gt;&lt;\\\/td&gt;\\n&lt;td style=\\&quot;text-align: left;\\&quot;&gt;&lt;img title=\\&quot;-white_check_mark-\\&quot; alt=\\&quot;-white_check_mark-\\&quot; class=\\&quot;smileys\\&quot; src=\\&quot;\\\/user\\\/data\\\/smileys\\\/emoji\\\/white_check_mark.png\\&quot; \\\/&gt;&lt;\\\/td&gt;\\n&lt;td style=\\&quot;text-align: left;\\&quot;&gt;boolean&lt;\\\/td&gt;\\n&lt;td style=\\&quot;text-align: left;\\&quot;&gt;Indicates whether the terminal shows a prompt to enter a tip (false), or predefined tipping options to choose from (true).&lt;\\\/td&gt;\\n&lt;\\\/tr&gt;\\n&lt;tr&gt;\\n&lt;td style=\\&quot;text-align: left;\\&quot;&gt; &lt;a href=\\&quot;https:\\\/\\\/docs.adyen.com\\\/api-explorer\\\/Management\\\/latest\\\/patch\\\/companies\\\/(companyId)\\\/terminalSettings#request-gratuities-predefinedTipEntries\\&quot; class=\\&quot;codeLabel  external-link no-image\\&quot; target=\\&quot;_blank\\&quot; rel=\\&quot;nofollow noopener noreferrer\\&quot;&gt;predefinedTipEntries&lt;\\\/a&gt;&lt;\\\/td&gt;\\n&lt;td style=\\&quot;text-align: left;\\&quot;&gt;&lt;img title=\\&quot;-white_check_mark-\\&quot; alt=\\&quot;-white_check_mark-\\&quot; class=\\&quot;smileys\\&quot; src=\\&quot;\\\/user\\\/data\\\/smileys\\\/emoji\\\/white_check_mark.png\\&quot; \\\/&gt;&lt;\\\/td&gt;\\n&lt;td style=\\&quot;text-align: left;\\&quot;&gt;array [string]&lt;\\\/td&gt;\\n&lt;td style=\\&quot;text-align: left;\\&quot;&gt;Tipping options the shopper can choose from if &lt;code&gt;usePredefinedTipEntries&lt;\\\/code&gt; is &lt;span translate=\\&quot;no\\&quot;&gt;&lt;strong&gt;true&lt;\\\/strong&gt;&lt;\\\/span&gt;. The maximum number of predefined options is four, or three plus the option to enter a custom tip. The options can be a mix of: &lt;ul&gt;&lt;li markdown=\\&quot;1\\&quot;&gt;A percentage of the transaction amount. Example: 5% &lt;li markdown=\\&quot;1\\&quot;&gt;A tip amount in minor units. Example: 500 for a EUR 5 tip.&lt;\\\/li&gt;&lt;\\\/ul&gt;&lt;\\\/td&gt;\\n&lt;\\\/tr&gt;\\n&lt;tr&gt;\\n&lt;td style=\\&quot;text-align: left;\\&quot;&gt; &lt;a href=\\&quot;https:\\\/\\\/docs.adyen.com\\\/api-explorer\\\/Management\\\/latest\\\/patch\\\/companies\\\/(companyId)\\\/terminalSettings#request-gratuities-allowCustomAmount\\&quot; class=\\&quot;codeLabel  external-link no-image\\&quot; target=\\&quot;_blank\\&quot; rel=\\&quot;nofollow noopener noreferrer\\&quot;&gt;allowCustomAmount&lt;\\\/a&gt;&lt;\\\/td&gt;\\n&lt;td style=\\&quot;text-align: left;\\&quot;&gt;&lt;img title=\\&quot;-white_check_mark-\\&quot; alt=\\&quot;-white_check_mark-\\&quot; class=\\&quot;smileys\\&quot; src=\\&quot;\\\/user\\\/data\\\/smileys\\\/emoji\\\/white_check_mark.png\\&quot; \\\/&gt;&lt;\\\/td&gt;\\n&lt;td style=\\&quot;text-align: left;\\&quot;&gt;boolean&lt;\\\/td&gt;\\n&lt;td style=\\&quot;text-align: left;\\&quot;&gt;Indicates whether one of the predefined tipping options is to let the shopper enter a custom tip. If &lt;span translate=\\&quot;no\\&quot;&gt;&lt;strong&gt;true&lt;\\\/strong&gt;&lt;\\\/span&gt;, only three of the other options defined in &lt;code&gt;predefinedTipEntries&lt;\\\/code&gt; are shown.&lt;\\\/td&gt;\\n&lt;\\\/tr&gt;\\n&lt;\\\/tbody&gt;\\n&lt;\\\/table&gt;\\n&lt;div data-component-wrapper=\\&quot;code-sample\\&quot;&gt;\\n&lt;code-sample :title=\\&quot;&#039;Configure tipping with Management API &#039;\\&quot; :id=\\&quot;&#039;configure-tipping-MAPI&#039;\\&quot; :code-data=\\&quot;[{&amp;quot;language&amp;quot;:&amp;quot;bash&amp;quot;,&amp;quot;tabTitle&amp;quot;:&amp;quot;curl&amp;quot;,&amp;quot;content&amp;quot;:&amp;quot;curl \\\\&amp;quot;https:\\\\\\\/\\\\\\\/management-test.adyen.com\\\\\\\/v3\\\\\\\/terminals\\\\\\\/{terminalId}\\\\\\\/terminalSettings\\\\&amp;quot; \\\\\\\\\\\\n-H &#039;X-API-key: ADYEN_API_KEY&#039; \\\\\\\\\\\\n-H &#039;Content-Type: application\\\\\\\/json&#039; \\\\\\\\\\\\n-X PATCH \\\\\\\\\\\\n-d &#039;{\\\\n       \\\\&amp;quot;gratuities\\\\&amp;quot;:[\\\\n          {\\\\n             \\\\&amp;quot;currency\\\\&amp;quot;:\\\\&amp;quot;EUR\\\\&amp;quot;,\\\\n             \\\\&amp;quot;predefinedTipEntries\\\\&amp;quot;:[\\\\n                \\\\&amp;quot;10%\\\\&amp;quot;,\\\\n                \\\\&amp;quot;15%\\\\&amp;quot;,\\\\n                \\\\&amp;quot;20%\\\\&amp;quot;\\\\n             ],\\\\n             \\\\&amp;quot;usePredefinedTipEntries\\\\&amp;quot;:true,\\\\n             \\\\&amp;quot;allowCustomAmount\\\\&amp;quot;:true\\\\n          }\\\\n       ]\\\\n    }&#039;&amp;quot;},{&amp;quot;language&amp;quot;:&amp;quot;java&amp;quot;,&amp;quot;tabTitle&amp;quot;:&amp;quot;Java&amp;quot;,&amp;quot;content&amp;quot;:&amp;quot;\\\\\\\/\\\\\\\/ Adyen Java API Library v40.0.0\\\\nimport com.adyen.Client;\\\\nimport com.adyen.enums.Environment;\\\\nimport com.adyen.model.management.*;\\\\nimport java.time.OffsetDateTime;\\\\nimport java.util.*;\\\\nimport com.adyen.service.management.*;\\\\n\\\\nClient client = new Client(\\\\&amp;quot;ADYEN_API_KEY\\\\&amp;quot;, Environment.TEST);\\\\n\\\\n\\\\\\\/\\\\\\\/ Create the request object(s)\\\\nGratuity gratuity1 = new Gratuity()\\\\n  .predefinedTipEntries(Arrays.asList(\\\\&amp;quot;10%\\\\&amp;quot;, \\\\&amp;quot;15%\\\\&amp;quot;, \\\\&amp;quot;20%\\\\&amp;quot;))\\\\n  .allowCustomAmount(true)\\\\n  .usePredefinedTipEntries(true)\\\\n  .currency(\\\\&amp;quot;EUR\\\\&amp;quot;);\\\\n\\\\nTerminalSettings terminalSettings = new TerminalSettings()\\\\n  .gratuities(Arrays.asList(gratuity1));\\\\n\\\\n\\\\\\\/\\\\\\\/ Send the request\\\\nTerminalSettingsTerminalLevelApi service = new TerminalSettingsTerminalLevelApi(client);\\\\nTerminalSettings response = service.updateTerminalSettings(\\\\&amp;quot;terminalId\\\\&amp;quot;, terminalSettings, null);&amp;quot;},{&amp;quot;language&amp;quot;:&amp;quot;php&amp;quot;,&amp;quot;tabTitle&amp;quot;:&amp;quot;PHP&amp;quot;,&amp;quot;content&amp;quot;:&amp;quot;&amp;lt;?php\\\\n\\\\\\\/\\\\\\\/ Adyen PHP API Library v28.3.0\\\\nuse Adyen\\\\\\\\Client;\\\\nuse Adyen\\\\\\\\Environment;\\\\nuse Adyen\\\\\\\\Model\\\\\\\\Management\\\\\\\\Gratuity;\\\\nuse Adyen\\\\\\\\Model\\\\\\\\Management\\\\\\\\TerminalSettings;\\\\nuse Adyen\\\\\\\\Service\\\\\\\\Management\\\\\\\\TerminalSettingsTerminalLevelApi;\\\\n\\\\n$client = new Client();\\\\n$client-&amp;gt;setXApiKey(\\\\&amp;quot;ADYEN_API_KEY\\\\&amp;quot;);\\\\n$client-&amp;gt;setEnvironment(Environment::TEST);\\\\n\\\\n\\\\n\\\\\\\/\\\\\\\/ Create the request object(s)\\\\n$gratuity1 = new Gratuity();\\\\n$gratuity1\\\\n  -&amp;gt;setPredefinedTipEntries(array(\\\\&amp;quot;10%\\\\&amp;quot;, \\\\&amp;quot;15%\\\\&amp;quot;, \\\\&amp;quot;20%\\\\&amp;quot;))\\\\n  -&amp;gt;setAllowCustomAmount(true)\\\\n  -&amp;gt;setUsePredefinedTipEntries(true)\\\\n  -&amp;gt;setCurrency(\\\\&amp;quot;EUR\\\\&amp;quot;);\\\\n\\\\n$terminalSettings = new TerminalSettings();\\\\n$terminalSettings\\\\n  -&amp;gt;setGratuities(array($gratuity1));\\\\n\\\\n\\\\\\\/\\\\\\\/ Send the request\\\\n$service = new TerminalSettingsTerminalLevelApi($client);\\\\n$response = $service-&amp;gt;updateTerminalSettings(&#039;terminalId&#039;, $terminalSettings);&amp;quot;},{&amp;quot;language&amp;quot;:&amp;quot;cs&amp;quot;,&amp;quot;tabTitle&amp;quot;:&amp;quot;C#&amp;quot;,&amp;quot;content&amp;quot;:&amp;quot;\\\\\\\/\\\\\\\/ Adyen .NET API Library v32.2.1\\\\nusing Adyen;\\\\nusing Environment = Adyen.Model.Environment;\\\\nusing Adyen.Model;\\\\nusing Adyen.Model.Management;\\\\nusing Adyen.Service.Management;\\\\n\\\\nvar config = new Config()\\\\n{\\\\n    XApiKey = \\\\&amp;quot;ADYEN_API_KEY\\\\&amp;quot;,\\\\n    Environment = Environment.Test\\\\n};\\\\nvar client = new Client(config);\\\\n\\\\n\\\\\\\/\\\\\\\/ Create the request object(s)\\\\nGratuity gratuity1 = new Gratuity\\\\n{\\\\n  PredefinedTipEntries = { \\\\&amp;quot;10%\\\\&amp;quot;, \\\\&amp;quot;15%\\\\&amp;quot;, \\\\&amp;quot;20%\\\\&amp;quot; },\\\\n  AllowCustomAmount = true,\\\\n  UsePredefinedTipEntries = true,\\\\n  Currency = \\\\&amp;quot;EUR\\\\&amp;quot;\\\\n};\\\\n\\\\nTerminalSettings terminalSettings = new TerminalSettings\\\\n{\\\\n  Gratuities = new List&amp;lt;Gratuity&amp;gt;{ gratuity1 }\\\\n};\\\\n\\\\n\\\\\\\/\\\\\\\/ Send the request\\\\nvar service = new TerminalSettingsTerminalLevelService(client);\\\\nvar response = service.UpdateTerminalSettings(\\\\&amp;quot;terminalId\\\\&amp;quot;, terminalSettings);&amp;quot;},{&amp;quot;language&amp;quot;:&amp;quot;js&amp;quot;,&amp;quot;tabTitle&amp;quot;:&amp;quot;NodeJS (JavaScript)&amp;quot;,&amp;quot;content&amp;quot;:&amp;quot;\\\\\\\/\\\\\\\/ Adyen Node API Library v30.0.0\\\\nconst { Client, ManagementAPI } = require(&#039;@adyen\\\\\\\/api-library&#039;);\\\\n\\\\nconst config = new Config({\\\\n  apiKey: \\\\&amp;quot;ADYEN_API_KEY\\\\&amp;quot;,\\\\n  environment: EnvironmentEnum.TEST\\\\n});\\\\n\\\\nconst client = new Client(config);\\\\n\\\\n\\\\\\\/\\\\\\\/ Create the request object(s)\\\\nconst terminalSettings = {\\\\n  gratuities: [ {\\\\n    currency: \\\\&amp;quot;EUR\\\\&amp;quot;,\\\\n    predefinedTipEntries: [ \\\\&amp;quot;10%\\\\&amp;quot;, \\\\&amp;quot;15%\\\\&amp;quot;, \\\\&amp;quot;20%\\\\&amp;quot; ],\\\\n    usePredefinedTipEntries: true,\\\\n    allowCustomAmount: true\\\\n  } ]\\\\n}\\\\n\\\\n\\\\\\\/\\\\\\\/ Send the request\\\\nconst managementAPI = new ManagementAPI(client);\\\\nconst response = managementAPI.TerminalSettingsTerminalLevelApi.updateTerminalSettings(\\\\&amp;quot;terminalId\\\\&amp;quot;, terminalSettings);&amp;quot;},{&amp;quot;language&amp;quot;:&amp;quot;go&amp;quot;,&amp;quot;tabTitle&amp;quot;:&amp;quot;Go&amp;quot;,&amp;quot;content&amp;quot;:&amp;quot;\\\\\\\/\\\\\\\/ Adyen Go API Library v21.1.0\\\\nimport (\\\\n  \\\\&amp;quot;context\\\\&amp;quot;\\\\n  \\\\&amp;quot;github.com\\\\\\\/adyen\\\\\\\/adyen-go-api-library\\\\\\\/v21\\\\\\\/src\\\\\\\/common\\\\&amp;quot;\\\\n  \\\\&amp;quot;github.com\\\\\\\/adyen\\\\\\\/adyen-go-api-library\\\\\\\/v21\\\\\\\/src\\\\\\\/adyen\\\\&amp;quot;\\\\n  \\\\&amp;quot;github.com\\\\\\\/adyen\\\\\\\/adyen-go-api-library\\\\\\\/v21\\\\\\\/src\\\\\\\/management\\\\&amp;quot;\\\\n)\\\\nclient := adyen.NewClient(&amp;amp;common.Config{\\\\n  ApiKey:      \\\\&amp;quot;ADYEN_API_KEY\\\\&amp;quot;,\\\\n  Environment: common.TestEnv,\\\\n})\\\\n\\\\n\\\\\\\/\\\\\\\/ Create the request object(s)\\\\ngratuity1 := management.Gratuity{\\\\n  PredefinedTipEntries: []string{\\\\n    \\\\&amp;quot;10%\\\\&amp;quot;, \\\\&amp;quot;15%\\\\&amp;quot;, \\\\&amp;quot;20%\\\\&amp;quot;,\\\\n  },\\\\n  AllowCustomAmount: common.PtrBool(true),\\\\n  UsePredefinedTipEntries: common.PtrBool(true),\\\\n  Currency: common.PtrString(\\\\&amp;quot;EUR\\\\&amp;quot;),\\\\n}\\\\n\\\\nterminalSettings := management.TerminalSettings{\\\\n  Gratuities: []management.Gratuity{\\\\n      gratuity1,\\\\n  },\\\\n}\\\\n\\\\n\\\\\\\/\\\\\\\/ Send the request\\\\nservice := client.Management()\\\\nreq := service.TerminalSettingsTerminalLevelApi.UpdateTerminalSettingsInput(\\\\&amp;quot;terminalId\\\\&amp;quot;).TerminalSettings(terminalSettings)\\\\nres, httpRes, err := service.TerminalSettingsTerminalLevelApi.UpdateTerminalSettings(context.Background(), req)&amp;quot;},{&amp;quot;language&amp;quot;:&amp;quot;py&amp;quot;,&amp;quot;tabTitle&amp;quot;:&amp;quot;Python&amp;quot;,&amp;quot;content&amp;quot;:&amp;quot;# Adyen Python API Library v14.0.0\\\\nimport Adyen\\\\n\\\\nadyen = Adyen.Adyen()\\\\nadyen.client.xapikey = \\\\&amp;quot;ADYEN_API_KEY\\\\&amp;quot;\\\\nadyen.client.platform = \\\\&amp;quot;test\\\\&amp;quot; # The environment to use library in.\\\\n\\\\n# Create the request object(s)\\\\njson_request = {\\\\n  \\\\&amp;quot;gratuities\\\\&amp;quot;: [ {\\\\n    \\\\&amp;quot;currency\\\\&amp;quot;: \\\\&amp;quot;EUR\\\\&amp;quot;,\\\\n    \\\\&amp;quot;predefinedTipEntries\\\\&amp;quot;: [ \\\\&amp;quot;10%\\\\&amp;quot;, \\\\&amp;quot;15%\\\\&amp;quot;, \\\\&amp;quot;20%\\\\&amp;quot; ],\\\\n    \\\\&amp;quot;usePredefinedTipEntries\\\\&amp;quot;: True,\\\\n    \\\\&amp;quot;allowCustomAmount\\\\&amp;quot;: True\\\\n  } ]\\\\n}\\\\n\\\\n# Send the request\\\\nresult = adyen.management.terminal_settings_terminal_level_api.update_terminal_settings(request=json_request, terminalId=\\\\&amp;quot;terminalId\\\\&amp;quot;)&amp;quot;},{&amp;quot;language&amp;quot;:&amp;quot;rb&amp;quot;,&amp;quot;tabTitle&amp;quot;:&amp;quot;Ruby&amp;quot;,&amp;quot;content&amp;quot;:&amp;quot;# Adyen Ruby API Library v11.0.0\\\\nrequire \\\\&amp;quot;adyen-ruby-api-library\\\\&amp;quot;\\\\n\\\\nadyen = Adyen::Client.new\\\\nadyen.api_key = &#039;ADYEN_API_KEY&#039;\\\\nadyen.env = :test # Set to \\\\&amp;quot;live\\\\&amp;quot; for live environment\\\\n\\\\n# Create the request object(s)\\\\nrequest_body = {\\\\n  :gratuities =&amp;gt; [ {\\\\n    :currency =&amp;gt; &#039;EUR&#039;,\\\\n    :predefinedTipEntries =&amp;gt; [ &#039;10%&#039;, &#039;15%&#039;, &#039;20%&#039; ],\\\\n    :usePredefinedTipEntries =&amp;gt; true,\\\\n    :allowCustomAmount =&amp;gt; true\\\\n  } ]\\\\n}\\\\n\\\\n# Send the request\\\\nresult = adyen.management.terminal_settings_terminal_level_api.update_terminal_settings(request_body, &#039;terminalId&#039;)&amp;quot;},{&amp;quot;language&amp;quot;:&amp;quot;ts&amp;quot;,&amp;quot;tabTitle&amp;quot;:&amp;quot;NodeJS (TypeScript)&amp;quot;,&amp;quot;content&amp;quot;:&amp;quot;\\\\\\\/\\\\\\\/ Adyen Node API Library v30.0.0\\\\nimport { Client, ManagementAPI, Types } from \\\\&amp;quot;@adyen\\\\\\\/api-library\\\\&amp;quot;;\\\\n\\\\nconst config = new Config({\\\\n  apiKey: \\\\&amp;quot;ADYEN_API_KEY\\\\&amp;quot;,\\\\n  environment: EnvironmentEnum.TEST\\\\n});\\\\n\\\\nconst client = new Client(config);\\\\n\\\\n\\\\\\\/\\\\\\\/ Create the request object(s)\\\\nconst gratuity1: Types.management.Gratuity = {\\\\n  predefinedTipEntries: [\\\\&amp;quot;10%\\\\&amp;quot;, \\\\&amp;quot;15%\\\\&amp;quot;, \\\\&amp;quot;20%\\\\&amp;quot;],\\\\n  allowCustomAmount: true,\\\\n  usePredefinedTipEntries: true,\\\\n  currency: \\\\&amp;quot;EUR\\\\&amp;quot;\\\\n};\\\\n\\\\nconst terminalSettings: Types.management.TerminalSettings = {\\\\n  gratuities: [gratuity1]\\\\n};\\\\n\\\\n\\\\\\\/\\\\\\\/ Send the request\\\\nconst managementAPI = new ManagementAPI(client);\\\\nconst response = managementAPI.TerminalSettingsTerminalLevelApi.updateTerminalSettings(\\\\&amp;quot;terminalId\\\\&amp;quot;, terminalSettings);&amp;quot;}]\\&quot; :enable-copy-link-to-code-block=\\&quot;true\\&quot; :code-sample-card-size=\\&quot;&#039;fullsize&#039;\\&quot;&gt;&lt;\\\/code-sample&gt;\\n&lt;\\\/div&gt;\\n&lt;\\\/li&gt;\\n&lt;li&gt;\\n&lt;p&gt;The response returns all settings that your API credential has access to, including the ones that you defined in the request.&lt;\\\/p&gt;\\n&lt;\\\/li&gt;\\n&lt;\\\/ol&gt;\\n&quot;,&quot;altTitle&quot;:&quot;set-up-api-3&quot;,&quot;oldTabId&quot;:1,&quot;relation&quot;:&quot;&quot;}]\"\n            :should-update-when-url-changes='true'>\n        <\/tabs>\n    <\/div>\n<\/div>\n\n<h2 id=\"indirect-tipping\">Ask for a total amount<\/h2>\n<p>The terminal shows the original purchase amount and a prompt to enter the total amount. This must at least be equal to the original amount. By entering a higher total amount, the customer adds a tip. After the customer enters the total amount, the terminal asks the customer to present their card and, if required, complete the payment by providing their PIN or signature.<\/p>\n<p>To use tipping by asking for a total amount:<\/p>\n<ol>\n<li>Contact our <a href=\"https:\/\/ca-test.adyen.com\/ca\/ca\/contactUs\/support.shtml?form=other\" target=\"_blank\" rel=\"nofollow noopener noreferrer\" class=\"external-link no-image\">Support Team<\/a> to enable tipping by asking for a total amount.<\/li>\n<li><a href=\"#payment-tipping-terminal\">Make payment requests<\/a> using the tender option <span translate=\"no\"><strong>AskGratuity<\/strong><\/span>.<\/li>\n<\/ol>\n<p>For currencies that in practice do not use decimals in transactions (like SEK), we make sure the tipping screen doesn't show decimals.<\/p>\n<table>\n<thead>\n<tr>\n<th style=\"text-align: left;\"><\/th>\n<th style=\"text-align: left;\"><\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td style=\"text-align: left;\">Total tipping for currency with decimals: <br> <img alt=\"\" src=\"\/images\/e\/4\/f\/b\/6\/e4fb6546e85446c233d9aa6ba1443fca7b55c70d-screen-entipping-enter-total-amount.png\" \/><\/td>\n<td style=\"text-align: left;\">Total tipping for currency without decimals: <br> <img alt=\"\" src=\"\/images\/f\/e\/e\/5\/7\/fee576367ad82b16dbe1b304b0683b97024006c2-screen-entipping-enter-total-amount-sek.png\" \/><\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<h2 id=\"payment-tipping-terminal\">Make a payment<\/h2>\n<p>To trigger the payment terminal to ask the customer for a tip amount or a total amount, you need to make a payment request with the <span translate=\"no\"><strong>AskGratuity<\/strong><\/span> <a href=\"\/point-of-sale\/add-data\/tender-options\">tender option<\/a>.<\/p>\n<ol>\n<li>\n<p><a href=\"\/point-of-sale\/basic-tapi-integration\/make-a-payment#make-a-payment\">Make a payment request<\/a>, specifying:<\/p>\n<ul>\n<li>\n<p>The standard <a href=\"\/point-of-sale\/design-your-integration\/terminal-api#request-message-header\">\n  <code>SaleToPOIRequest.MessageHeader<\/code>\n<\/a> object, with <code>MessageClass<\/code> set to <span translate=\"no\"><strong>Service<\/strong><\/span> and <code>MessageCategory<\/code> set to <span translate=\"no\"><strong>Payment<\/strong><\/span>.<\/p>\n<table>\n<thead>\n<tr>\n<th style=\"text-align: left;\">Parameter<\/th>\n<th style=\"text-align: center;\">Required<\/th>\n<th style=\"text-align: left;\">Description<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td style=\"text-align: left;\"><code>ProtocolVersion<\/code><\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<td style=\"text-align: left;\"><strong>3.0<\/strong><\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>MessageClass<\/code><\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<td style=\"text-align: left;\"><span translate=\"no\"><strong>Service<\/strong><\/span><\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>MessageCategory<\/code><\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<td style=\"text-align: left;\"><span translate=\"no\"><strong>Payment<\/strong><\/span><\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>MessageType<\/code><\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<td style=\"text-align: left;\"><span translate=\"no\"><strong>Request<\/strong><\/span><\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>ServiceID<\/code><\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<td style=\"text-align: left;\">Your unique ID for this request, consisting of 1-10 alphanumeric characters. Must be unique within the last 48 hours for the terminal (<code>POIID<\/code>) being used.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>SaleID<\/code><\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<td style=\"text-align: left;\">Your unique ID for the POS system component to send this request from.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>POIID<\/code><\/td>\n<td style=\"text-align: center;\"><img title=\"-white_check_mark-\" alt=\"-white_check_mark-\" class=\"smileys\" src=\"\/user\/data\/smileys\/emoji\/white_check_mark.png\" \/><\/td>\n<td style=\"text-align: left;\">The unique ID of the terminal to send this request to. Format: <em>[device model]-[serial number]<\/em>.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<\/li>\n<\/ul>\n<ul>\n<li>\n<p>The  <a href=\"https:\/\/docs.adyen.com\/api-explorer\/terminal-api\/latest\/post\/payment\" class=\"codeLabel  external-link no-image\" target=\"_blank\" rel=\"nofollow noopener noreferrer\">PaymentRequest<\/a> object with:<\/p>\n<table>\n<thead>\n<tr>\n<th style=\"text-align: left;\">Parameter<\/th>\n<th style=\"text-align: left;\">Description<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td style=\"text-align: left;\"><code>SaleData.SaleToAcquirerData<\/code><\/td>\n<td style=\"text-align: left;\">The <span translate=\"no\"><strong>AskGratuity<\/strong><\/span> tender option that triggers the terminal to start the tipping flow. <p>See the <a href=\"#sale-to-acquirer-data\">instructions below<\/a>.<\/p><\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><code>PaymentTransaction.AmountsReq<\/code><\/td>\n<td style=\"text-align: left;\">An object with: <ul><li markdown=\"1\"><code>Currency<\/code>: The transaction <a href=\"\/development-resources\/currency-codes\">currency<\/a>.<\/li><li markdown=\"1\"><code>RequestedAmount<\/code>: The purchase amount, with decimals.<\/li><\/ul><\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<p>In <code>SaleData.SaleToAcquirerData<\/code>, specify the tender option in one of the following formats:<br \/>\n<a id=\"sale-to-acquirer-data\"><\/a><\/p>\n<ul>\n<li>\n<p>Option 1: a JSON object converted to a Base64 encoded string.<br \/>\nEncode <code>{\"tenderOption\": \"AskGratuity\"}<\/code> to Base64, and pass the resulting string:<br \/>\n<code>\"SaleToAcquirerData\": \"eyJ0ZW5kZXJPcHRpb24iOiAiQXNrR3JhdHVpdHkifQ==\"<\/code><\/p>\n<\/li>\n<li>\n<p>Option 2: a key-value pair:<br \/>\n<code>\"SaleToAcquirerData\": \"tenderOption=AskGratuity\"<\/code><\/p>\n<\/li>\n<\/ul>\n<p>The format that you use here, will also be the format of the <code>AdditionalResponse<\/code> that you receive. If there are more tender options (for example <span translate=\"no\"><strong>ReceiptHandler<\/strong><\/span> ) or other data elements that you need to pass in the <code>SaleToAcquirerData<\/code> field, see <a href=\"\/point-of-sale\/add-data\">Add information to a payment<\/a>.<\/p>\n<\/li>\n<\/ul>\n<p>The example below shows how to show tipping options and initiate a transaction of <strong>EUR&nbsp;142.50<\/strong>.<\/p>\n<div data-component-wrapper=\"code-sample\">\n<code-sample :title=\"'Payment request with tipping'\" :id=\"''\" :code-data='[{\"language\":\"json\",\"tabTitle\":\"\",\"content\":\"{\\n  \\\"SaleToPOIRequest\\\":{\\n    \\\"MessageHeader\\\":{\\n      \\\"ProtocolVersion\\\":\\\"3.0\\\",\\n      \\\"MessageClass\\\":\\\"Service\\\",\\n      \\\"MessageCategory\\\":\\\"Payment\\\",\\n      \\\"MessageType\\\":\\\"Request\\\",\\n      \\\"SaleID\\\":\\\"POSSystemID12345\\\",\\n      \\\"ServiceID\\\":\\\"0207111104\\\",\\n      \\\"POIID\\\":\\\"P400Plus-275688710\\\"\\n    },\\n    \\\"PaymentRequest\\\":{\\n      \\\"SaleData\\\":{\\n        \\\"SaleTransactionID\\\":{\\n          \\\"TransactionID\\\":\\\"27908\\\",\\n          \\\"TimeStamp\\\":\\\"2019-12-17T10:11:03.000Z\\\"\\n        },\\n        \\\"SaleToAcquirerData\\\": \\\"tenderOption=AskGratuity,ReceiptHandler\\\"\\n      },\\n      \\\"PaymentTransaction\\\":{\\n        \\\"AmountsReq\\\":{\\n          \\\"Currency\\\":\\\"EUR\\\",\\n          \\\"RequestedAmount\\\":142.50\\n        }\\n      }\\n    }\\n  }\\n}\"}]' :enable-copy-link-to-code-block=\"true\" :code-sample-card-size=\"'fullsize'\"><\/code-sample>\n<\/div>\n<p>When the customer has responded, the payment terminal sends the request for the original purchase amount plus the tip amount to the Adyen payments platform.<\/p>\n<p>If successful, the terminal shows the payment is approved.<\/p>\n<\/li>\n<li>\n<p>In the  <a href=\"https:\/\/docs.adyen.com\/api-explorer\/terminal-api\/latest\/post\/payment#responses-200\" class=\"codeLabel  external-link no-image\" target=\"_blank\" rel=\"nofollow noopener noreferrer\">PaymentResponse<\/a> note the following:<\/p>\n<ul>\n<li>\n<p><code>PaymentReceipt<\/code>: 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.<\/p>\n<\/li>\n<li>\n<p><code>PaymentResult.AmountsResp<\/code>:<\/p>\n<ul>\n<li><code>TipAmount<\/code>: the amount of the tip. If the customer didn't add a tip, this field is not included.<\/li>\n<li><code>AuthorizedAmount<\/code>: the total authorized amount of the transaction, consisting of the original purchase amount plus the tip amount.<\/li>\n<li>\n<p><code>Currency<\/code>: currency of the payment.<\/p>\n <!-- list separator -->\n<\/li>\n<\/ul>\n<\/li>\n<li>\n<p><code>Response.AdditionalResponse<\/code>: 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:<\/p>\n<ul>\n<li><code>posadditionalamounts.originalAmountValue<\/code>: the original purchase amount in <a href=\"\/development-resources\/currency-codes\">minor units<\/a>.<\/li>\n<li><code>posAmountGratuityValue<\/code>: the tip amount in minor units.<\/li>\n<li><code>authorisedAmountValue<\/code>: the total authorized amount in minor units.<\/li>\n<\/ul>\n<\/li>\n<\/ul>\n<p>The example below shows the response for a transaction of <strong>EUR&nbsp;142.50<\/strong> with a 10% tip added.<\/p>\n<div data-component-wrapper=\"code-sample\">\n<code-sample :title=\"'Payment response with tip added'\" :id=\"''\" :code-data='[{\"language\":\"json\",\"tabTitle\":\"\",\"content\":\"{\\n  \\\"SaleToPOIResponse\\\": {\\n    \\\"PaymentResponse\\\": {\\n      \\\"POIData\\\": {\\n        \\\"POITransactionID\\\": {\\n          \\\"TimeStamp\\\": \\\"2019-12-17T10:11:12.000Z\\\",\\n          \\\"TransactionID\\\": \\\"8ha5001575467786000.NC6HT9CRT65ZGN82\\\"\\n        }\\n          {...},\\n      \\\"SaleData\\\": {...},\\n        \\\"PaymentReceipt\\\": [...],\\n        \\\"PaymentResult\\\": {\\n          \\\"AuthenticationMethod\\\": [...],\\n          \\\"OnlineFlag\\\": true,\\n          \\\"PaymentAcquirerData\\\": {...},\\n          \\\"PaymentInstrumentData\\\": {...},\\n          \\\"AmountsResp\\\": {\\n            \\\"TipAmount\\\": 14.25,\\n            \\\"AuthorizedAmount\\\": 156.75,\\n            \\\"Currency\\\": \\\"EUR\\\"\\n          }\\n        },\\n        \\\"Response\\\": {\\n          \\\"Result\\\": \\\"Success\\\",\\n          \\\"AdditionalResponse\\\": \\\"...posadditionalamounts.originalAmountValue=14250&amp;...posAmountGratuityValue=1425&amp;gratuityAmount=1425&amp;...authorisedAmountValue=15675...&amp;posAuthAmountValue=15675&amp;posadditionalamounts.gratuityAmount=1425\\\"\\n        }\\n      },\\n    \\\"MessageHeader\\\": {...}\\n  }\\n}\"}]' :enable-copy-link-to-code-block=\"true\" :code-sample-card-size=\"'fullsize'\"><\/code-sample>\n<\/div>\n<\/li>\n<\/ol>\n<h2 id=\"webhooks\">Keep your staff informed with display notifications<\/h2>\n<p>While your customer is interacting with the terminal, you can keep your staff informed of the tip amount by showing progress messages in your POS app.<\/p>\n<p>These messages are delivered using <em>display notifications<\/em>, which are webhooks that are sent to an endpoint that you specify. For information on how to set up and use display notifications, see our <a href=\"\/point-of-sale\/design-your-integration\/notifications\/display-notifications\">display notifications documentation<\/a>.<\/p>\n<h2>Add tip amounts to reporting<\/h2>\n<p>The <a href=\"\/reporting\/settlement-reconciliation\/transaction-level\/settlement-details-report\/#generate-and-download-reports\">Settlement details report<\/a> 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 <strong>gratuity amount<\/strong> column to your report in your <a href=\"https:\/\/ca-test.adyen.com\/\" target=\"_blank\" rel=\"nofollow noopener noreferrer\" class=\"external-link no-image\">Customer Area<\/a>.<\/p>\n<p>For more information on how to add the <strong>gratuity amount<\/strong> column to your report, see <a href=\"\/reporting\/settlement-reconciliation\/transaction-level\/settlement-details-report\/#configure-report-columns\">Configure report columns<\/a>.<\/p>\n<h2>High tip warning screen<\/h2>\n<p>When tipping from a terminal, it can happen that customers accidentally enter a tip amount that is too high. To prevent making a payment with incorrect amounts, the terminal can show a warning screen if the tip amount is higher than a certain percentage of the original purchase amount.<br \/>\nFor example, you can set the warning screen threshold to 50% of the original purchase amount. If the original amount is EUR&nbsp;100.00 and the customer enters a tip of EUR&nbsp;50.00 or more, the terminal shows the warning screen. The customer can then confirm the amount or go back to the previous screen.<\/p>\n<p>When enabled, the warning screen works with both methods of tipping from the terminal (asking for a tip amount, and asking for a total amount). This feature is available on standalone terminals as well as terminals integrated with a POS system.<\/p>\n<p>To show the high tip warning screen:<\/p>\n<ol>\n<li>Enable tipping by asking for a <a href=\"#direct-tipping\">tip amount<\/a> or <a href=\"#indirect-tipping\">total amount<\/a>.<\/li>\n<li>Ask our <a href=\"https:\/\/ca-test.adyen.com\/ca\/ca\/contactUs\/support.shtml?form=other\" target=\"_blank\" rel=\"nofollow noopener noreferrer\" class=\"external-link no-image\">Support Team<\/a> to enable the warning screen for tips that are higher than the percentage you want of the original purchase amount.<\/li>\n<li><a href=\"#payment-tipping-terminal\">Make payment requests<\/a> using the tender option <span translate=\"no\"><strong>AskGratuity<\/strong><\/span>.<\/li>\n<\/ol>\n<h2>See also<\/h2>\n<div class=\"see-also-links output-inline\" id=\"see-also\">\n<ul><li><a href=\"\/point-of-sale\/basic-tapi-integration\/make-a-payment\"\n                        target=\"_self\"\n                        >\n                    Make a payment\n                <\/a><\/li><li><a href=\"\/point-of-sale\/tipping\/tipping-from-terminal\/override-tipping-configuration\"\n                        target=\"_self\"\n                        >\n                    Override configured tipping options\n                <\/a><\/li><li><a href=\"\/point-of-sale\/add-data\/tender-options\"\n                        target=\"_self\"\n                        >\n                    Tender options\n                <\/a><\/li><li><a href=\"\/reporting\/settlement-reconciliation\/transaction-level\/settlement-details-report\/\"\n                        target=\"_self\"\n                        >\n                    Settlement details report\n                <\/a><\/li><\/ul><\/div>\n","url":"https:\/\/docs.adyen.com\/point-of-sale\/tipping\/tipping-from-terminal","articleFields":{"description":"Implement tipping where the customer adds a tip on the payment terminal.","parameters":{"standalone":"false"},"process":{"markdown":true,"twig":false},"twig_first":true,"never_cache_twig":true,"last_edit_on":"19-05-2026 17:06","feedback_component":true,"filters_component":false,"decision_tree":"[]","page_id":"acf689ee-6c47-41a9-98b6-1826017af280"},"algolia":{"url":"https:\/\/docs.adyen.com\/point-of-sale\/tipping\/tipping-from-terminal","title":"Tipping from the terminal","content":"This page describes how to set up and use tipping options for your customers on Adyen payment terminals. Depending on what is customary in your region, there are various ways to let the payment terminal ask your customers to add a tip:\n\nAsk for a tip amount: the customer chooses a predefined tipping option on the display or enters a custom tip amount (or chooses to skip giving a tip).\nAsk for a total amount: if the customer wants to give a tip, they enter a total amount that is higher than the original purchase amount. This is customary in Nordic countries\/regions.\n\nThe payment request to trigger tipping, is the same in both cases.\nRequirements\nBefore you begin, take into account the following requirements, limitations, and preparations.\n\n\n\nRequirement\nDescription\n\n\n\n\nIntegration type\nTerminal API integration with Adyen-provided payment terminals.\n\n\nWebhooks\nSet up standard webhooks and optionally display notifications to keep your staff informed.\n\n\nHardware\nAll terminal models are supported, except unattended terminals.\n\n\nSetup steps\nBefore you begin: If you want to prompt for a tip after card entry instead of before, ask our Support Team to enable that, and to enable single tap. If you want to prompt for a total amount instead of a tip amount, ask our Support Team to enable that.\n\n\n\nAsk for a tip amount\nYou can configure tipping options either from the Customer Area or with the Management API. Customers can then choose one of the predefined tipping options or enter a custom tip amount. Asking for a tip can appear before or after the customer enters their card. The default is tipping before card entry.\nBefore card entry\nThe terminal shows the purchase amount plus the tipping prompt or options you configured, and waits for the customer to respond. Then the terminal asks the customer to present their card and, if required, complete the payment by providing their PIN or signature.\nNo configuration from our side is needed for this.\nTo ask for a tip before card entry:\n\nConfigure tipping options in your Customer Area or with Management API.\nMake payment requests using the tender option AskGratuity.\n\nAfter card entry\nThe terminal shows the purchase amount and asks the customer to present their card. Then the terminal shows the tipping prompt or options you configured, and waits for the customer to respond. If required, the terminal asks the customer to complete the payment by providing their PIN or signature.\nTo ask for a tip after card entry:\n\nContact our Support Team and ask them to:\n\nEnable tipping options after card entry.\nOptionally, enable single tap. For contactless transactions, this ensures the terminal does not ask the customer to tap their card again after selecting a tip.\n\nConfigure tipping options in your Customer Area or with Management API.\nMake payment requests using the tender option AskGratuity.\n\nConfigure tipping options\nIt is possible to ask for a tip without tipping options. The payment terminal then shows a prompt to enter a tip plus an option for not giving a tip. To give a tip, the customer enters the amount and confirms.\nTo make tipping easier for your customers, you can define tipping options that your customer can select on the terminal. The options can be any combination of percentages, calculated amounts, and a custom amount. You can configure the terminal to show only the percentage, the percentage and the calculated total amount together and only the fixed tip amount.\n\n\n\n\n\n\n\n\n\n\nTipping without options:  \nTipping with percentage options:  \nPercentage and calculated tip amounts:  \n\n\n\nYou can configure tipping either from your Customer Area or by using the Management API.\n\n\n    \n        \n        \n    \n\n\nAsk for a total amount\nThe terminal shows the original purchase amount and a prompt to enter the total amount. This must at least be equal to the original amount. By entering a higher total amount, the customer adds a tip. After the customer enters the total amount, the terminal asks the customer to present their card and, if required, complete the payment by providing their PIN or signature.\nTo use tipping by asking for a total amount:\n\nContact our Support Team to enable tipping by asking for a total amount.\nMake payment requests using the tender option AskGratuity.\n\nFor currencies that in practice do not use decimals in transactions (like SEK), we make sure the tipping screen doesn't show decimals.\n\n\n\n\n\n\n\n\n\nTotal tipping for currency with decimals:  \nTotal tipping for currency without decimals:  \n\n\n\nMake a payment\nTo trigger the payment terminal to ask the customer for a tip amount or a total amount, you need to make a payment request with the AskGratuity tender option.\n\n\nMake a payment request, specifying:\n\n\nThe standard \n  SaleToPOIRequest.MessageHeader\n object, with MessageClass set to Service and MessageCategory set to Payment.\n\n\n\nParameter\nRequired\nDescription\n\n\n\n\nProtocolVersion\n\n3.0\n\n\nMessageClass\n\nService\n\n\nMessageCategory\n\nPayment\n\n\nMessageType\n\nRequest\n\n\nServiceID\n\nYour 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.\n\n\nSaleID\n\nYour unique ID for the POS system component to send this request from.\n\n\nPOIID\n\nThe unique ID of the terminal to send this request to. Format: [device model]-[serial number].\n\n\n\n\n\n\n\nThe  PaymentRequest object with:\n\n\n\nParameter\nDescription\n\n\n\n\nSaleData.SaleToAcquirerData\nThe AskGratuity tender option that triggers the terminal to start the tipping flow. See the instructions below.\n\n\nPaymentTransaction.AmountsReq\nAn object with: Currency: The transaction currency.RequestedAmount: The purchase amount, with decimals.\n\n\n\nIn SaleData.SaleToAcquirerData, specify the tender option in one of the following formats:\n\n\n\nOption 1: a JSON object converted to a Base64 encoded string.\nEncode {\"tenderOption\": \"AskGratuity\"} to Base64, and pass the resulting string:\n\"SaleToAcquirerData\": \"eyJ0ZW5kZXJPcHRpb24iOiAiQXNrR3JhdHVpdHkifQ==\"\n\n\nOption 2: a key-value pair:\n\"SaleToAcquirerData\": \"tenderOption=AskGratuity\"\n\n\nThe format that you use here, will also be the format of the AdditionalResponse that you receive. If there are more tender options (for example ReceiptHandler ) or other data elements that you need to pass in the SaleToAcquirerData field, see Add information to a payment.\n\n\nThe example below shows how to show tipping options and initiate a transaction of EUR&nbsp;142.50.\n\n\n\nWhen the customer has responded, the payment terminal sends the request for the original purchase amount plus the tip amount to the Adyen payments platform.\nIf successful, the terminal shows the payment is approved.\n\n\nIn the  PaymentResponse note the following:\n\n\nPaymentReceipt: 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.\n\n\nPaymentResult.AmountsResp:\n\nTipAmount: the amount of the tip. If the customer didn't add a tip, this field is not included.\nAuthorizedAmount: the total authorized amount of the transaction, consisting of the original purchase amount plus the tip amount.\n\nCurrency: currency of the payment.\n \n\n\n\n\nResponse.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:\n\nposadditionalamounts.originalAmountValue: the original purchase amount in minor units.\nposAmountGratuityValue: the tip amount in minor units.\nauthorisedAmountValue: the total authorized amount in minor units.\n\n\n\nThe example below shows the response for a transaction of EUR&nbsp;142.50 with a 10% tip added.\n\n\n\n\n\nKeep your staff informed with display notifications\nWhile your customer is interacting with the terminal, you can keep your staff informed of the tip amount by showing progress messages in your POS app.\nThese messages are delivered using display notifications, which are webhooks that are sent to an endpoint that you specify. For information on how to set up and use display notifications, see our display notifications documentation.\nAdd tip amounts to reporting\nThe Settlement details report 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.\nFor more information on how to add the gratuity amount column to your report, see Configure report columns.\nHigh tip warning screen\nWhen tipping from a terminal, it can happen that customers accidentally enter a tip amount that is too high. To prevent making a payment with incorrect amounts, the terminal can show a warning screen if the tip amount is higher than a certain percentage of the original purchase amount.\nFor example, you can set the warning screen threshold to 50% of the original purchase amount. If the original amount is EUR&nbsp;100.00 and the customer enters a tip of EUR&nbsp;50.00 or more, the terminal shows the warning screen. The customer can then confirm the amount or go back to the previous screen.\nWhen enabled, the warning screen works with both methods of tipping from the terminal (asking for a tip amount, and asking for a total amount). This feature is available on standalone terminals as well as terminals integrated with a POS system.\nTo show the high tip warning screen:\n\nEnable tipping by asking for a tip amount or total amount.\nAsk our Support Team to enable the warning screen for tips that are higher than the percentage you want of the original purchase amount.\nMake payment requests using the tender option AskGratuity.\n\nSee also\n\n\n                    Make a payment\n                \n                    Override configured tipping options\n                \n                    Tender options\n                \n                    Settlement details report\n                \n","type":"page","locale":"en","boost":17,"hierarchy":{"lvl0":"Home","lvl1":"In-person payments","lvl2":"Tipping","lvl3":"Tipping from the terminal"},"hierarchy_url":{"lvl0":"https:\/\/docs.adyen.com\/","lvl1":"https:\/\/docs.adyen.com\/point-of-sale","lvl2":"https:\/\/docs.adyen.com\/point-of-sale\/tipping","lvl3":"\/point-of-sale\/tipping\/tipping-from-terminal"},"levels":4,"category":"In-person payments","category_color":"green","tags":["Tipping","terminal"]},"articleFiles":{"screen-EN_Tipping-Enter-total-amount-Error.png":"<img alt=\"\" src=\"https:\/\/docs.adyen.com\/user\/pages\/docs\/03.point-of-sale\/28.tipping\/02.tipping-from-terminal\/screen-EN_Tipping-Enter-total-amount-Error.png\" \/>","screen-EN_Tipping-Enter-total-amount-SEK.png":"<img alt=\"\" src=\"https:\/\/docs.adyen.com\/images\/f\/9\/1\/f\/4\/f91f4d962e8f44e3af173bb53e529d8c9253fabc-screen-entipping-enter-total-amount-sek.png\" \/>","screen-EN_Tipping-Enter-total-amount.png":"<img alt=\"\" src=\"https:\/\/docs.adyen.com\/images\/9\/6\/0\/b\/2\/960b2509e3d383c80a5c4ec197b9b6900a55b751-screen-entipping-enter-total-amount.png\" \/>","configure-tipping-MAPI.js":"<p alt=\"\">configure-tipping-MAPI.js<\/p>"}}