{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-docs/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition","tabs","tab"]},"type":"markdown"},"seo":{"title":"Tipping","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"tipping","__idx":0},"children":["Tipping"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Tyro terminals can be configured to support tipping as part of the transaction workflow — for"," ","hospitality locations, or anyone accepting gratuities. When enabled, the customer enters the tip"," ","amount they choose to pay directly into the terminal during the transaction workflow."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["There are no extra steps for the POS to perform in terms of configuration or initiating the"," ","purchase request — there's no request parameter for tipping on any integration path. The terminal"," ","applies the tip amount automatically, and the applied amount is returned to the POS once the"," ","transaction completes."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The POS should:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Display the tip amount clearly on the sales receipt, labelled \"Tip\"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Include the tip amount in any POS reconciliation reports."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Store the tip-inclusive amount on the sales invoice, so it's added back automatically on refund."]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[".NET library only:"]}," don't confuse this with \"tip completion\" (writing a tip amount on the"," ","receipt for the customer to fill in) — that's a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["deprecated"]}," legacy mechanism, unrelated to the"," ","PIN-entry tipping described here."]}]},{"$$mdtype":"Tag","name":"Tabs","attributes":{"size":"medium"},"children":[{"$$mdtype":"Tag","name":"div","attributes":{"label":"JS library","disable":false},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Before you begin, check the certification criteria:"," ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/assets/certification_criteria_iclient_retail_hospitality.7bf0b2b5462961db882fcba1f1e9ddbec0d942cc7ee96278907994599bebf62a.d564e73d.pdf"},"children":["Certification Criteria Document"]},"."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["There are no request parameters for tipping in ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["initiatePurchase"]}," — the terminal handles it"," ","entirely, and the result is returned via ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transactionCompleteCallback"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"handling-the-response","__idx":1},"children":["Handling the response"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The integrated tipping function only uses ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transactionCompleteCallback"]},"; the relevant fields are"," ","given below."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Function"},"children":["Function"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Usage required"},"children":["Usage required"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transactionCompleteCallback"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Invoked when the transaction has been completed on the terminal. Called with a tip amount string field as part of the transactionData object, as shown below."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Required"]}]}]}]}]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Field"},"children":["Field"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Type"},"children":["Type"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Usage required"},"children":["Usage required"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tipAmount"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["String"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The applied tip amount for the transaction."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Required"]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"steps-to-follow","__idx":2},"children":["Steps to follow"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The applied tip amount is returned to the POS in the transaction response. The POS must specify"," ","any and all actions pertaining to how the tip amount is handled in the callback function."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The POS must obtain the returned tip amount and display it clearly on the POS sales receipt,"," ","accurately labelled \"Tip\". The POS must also store the tip-inclusive amount for the transaction"," ","on the sales invoice, so that when refunded, the tip amount is automatically added back on"," ","without any manual intervention."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transactionCompleteCallback"]}," contains the applied tip amount in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tipAmount"]}," field, as shown in"," ","the example below."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"var transactionCompleteCallbackImpl = function (response) {\n    console.log(\"Response = \" + JSON.stringify(response));\n\t\tvar tip=response.tipAmount/100;\n    if (response.customerReceipt) {\n\n        console.log(\"Customer Receipt = \" + JSON.stringify(response.customerReceipt));\n\n//Compiling the integrated receipt:\nif(transactionType==\"purchase\" && response.result==\"APPROVED\"){\n    total = ($(\"#amount\").val()/ 100);\n\t\ttotalamount = total+tip;\n    console.log(totalamount);\nvar posReceipt = formatReceipt(\"\\tTAX INVOICE       \\r\\n\\r\\n      Merchant 1655650     \\r\\n      Address line 1       \\r\\n      Address line 2       \\r\\n\\r\\n\\tAWESOME POS   \\r\\n\\t\\r\\nItems\\t\\t\\t$\\r\\nCoffee\\t\\t\\t\" + \"$\"+total + \"\\r\\n\\t\\r\\nSub-total\\t\\t\" + \"$\"+total + \"\\r\\n\\r\\nTip\\t\\t\\t\"+ \"$\"+ tip + \"\\r\\n\\r\\nTotal\\t\\t\\t\"+ \"$\"+(total+tip) +\"\\r\\n\\r\\nGST inc\\t\\t\\t$1.00\\r\\n\\r\\nPOS ID: 2\\r\\nRef: 12345abc\\r\\n04 Jan 2019 at 02:12 PM\\r\\n\\n\\n\\t--------------------\\n\\n\" + response.customerReceipt);\n        \n        console.log(posReceipt);\n\n        $(\"#customerReceipt\").html(posReceipt);\n\t\t\t\t\n}\nelse if(transactionType==\"refund\" && response.result==\"APPROVED\"){\nconsole.log(transactionType);\n var posReceipt = formatReceipt(\"\\tTAX INVOICE       \\r\\n\\r\\n      Merchant 1655650     \\r\\n      Address line 1       \\r\\n      Address line 2       \\r\\n\\r\\n\\tAWESOME POS   \\r\\n\\t\\r\\nREFUND\\t\\t\\t$\\r\\nAmount\\t\\t\\t\" + \"$\"+total + \"\\r\\n\\t\\r\\nSub-total\\t\\t\" + \"$\"+total   +\"\\r\\n\\r\\nTotal\\t\\t\\t\"+ \"$\"+total +\"\\r\\n\\r\\nGST inc\\t\\t\\t$1.00\\r\\n\\r\\nPOS ID: 2\\r\\nRef: 12345abc\\r\\n04 Jan 2019 at 02:12 PM\\r\\n\\n\\n\\t--------------------\\n\\n\" + response.customerReceipt);\n\n        \n        console.log(posReceipt);\n\n        $(\"#customerReceipt\").html(posReceipt);\n}\n\nelse{\nconsole.log(transactionType);\n var posReceipt = formatReceipt(\"\\t AWESOME POS      \\r\\n\\r\\n      Merchant 1655650     \\r\\n      Address line 1       \\r\\n      Address line 2       \\r\\n\\r\\n\\tAWESOME POS   \\r\\n\\t\\r\\nTRANSACTION FAILED\\t\\t\\r\\nResult:\\t\\t\\t\" + response.result + \"\\r\\n\\r\\nPOS ID: 2\\r\\nRef: 12345abc\\r\\n04 Jan 2019 at 02:12 PM\\r\\n\\n\\n\\t--------------------\\n\\n\" + response.customerReceipt);\n        \n        console.log(posReceipt);\n\n        $(\"#customerReceipt\").html(posReceipt);\n\n}\n\n       \n}\n    $(\"#result\").html(formatResult(response));\n};\n","lang":"javascript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"example-response","__idx":3},"children":["Example response"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A $100.00 purchase with a $10.00 tip and $1.00 surcharge:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n\"result\":\"APPROVED\",\n\"transactionId\":\"3783ea1cacae254808490fcf60bbd4eb221e\",\n\"cardType\":\"MasterCard\",\n\"transactionReference\":\"602145\",\n\"authorisationCode\":\"031054\",\n\"issuerActionCode\":\"00\",\n\"elidedPan\":\"xxxxxxxxxxxx5100\",\n\"rrn\":\"602145141255\",\n\"tipAmount\":\"10.00\",\n\"surchargeAmount\":\"1.00\",\n\"baseAmount\":\"111.00\",\n\"transactionAmount\":\"101.00\",\n\"customerReceipt\":\n\t\"      CUSTOMER COPY       \\n\n\t\\n\n\t      Merchant 1655650     \\n\n\t      Address line 1       \\n\n\t      Address line 2       \\n\n\t\\n\n\t    Tyro Payments EFTPOS   \\n\n\t\\n\n\tMasterCard\\n\n\tCard:    xxxxxxxxxxxx5100(s)\\n\n\t\\n\n\tPurchase     AUD     $100.00\\n\n\tSurcharge    AUD       $1.00\\n\n\tTip    \t\t AUD       $10.00\\n\n                  ----------\\n\n\tTotal        AUD     $111.00\\n\n\t\\n\n\tAPPROVED                  00\\n\n\t\\n\n\tTerminal ID: 8\\n\n\tTransaction Ref: 602145\\n\n\tAuthorisation No: 031054\\n\n\t04 Jan 2019 at 02:12 PM\\n\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"demo","__idx":4},"children":["Demo"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://jsfiddle.net/IntegrationSupport/c26phof3/6/"},"children":["JS Fiddle demo"]}," — demonstrates tipping"," ","alongside surcharge, with merchant/customer copies printed and a \"Refund last transaction\" button."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The refund function returns an HTTP 400 \"Invalid Transaction\" error in this demo — expected,"," ","since tip-inclusive amounts aren't registered magic numbers for the integration simulator."]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Don't click ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Save"]}," if you make changes in the JS Fiddle — click ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Run"]}," instead. Clicking Save"," ","may break the fiddle's functionality."]}]}]},{"$$mdtype":"Tag","name":"div","attributes":{"label":".NET library","disable":false},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"pin-entry-tipping-current","__idx":5},"children":["PIN-entry tipping (current)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The tip amount keyed into the terminal during a transaction is available on the"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TransactionCompleted"]}," event:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Method"},"children":["Method"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GetTipAmount()"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The tip amount that was keyed into the terminal during the transaction."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The full ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TransactionCompleted"]}," event reference is covered by"," ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/in-person-payments/pay-in-person/features/payment-cashout-refund"},"children":["Payment, cashout and refund"]},"."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Don't confuse this with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GetTipCompletionReference()"]}]},", below — that's a separate, deprecated"," ","mechanism."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"tip-completion-deprecated","__idx":6},"children":["Tip completion (deprecated)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Integrated tip completion — writing a tip amount on the receipt for the customer to fill in — is"," ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["no longer available"]},". The PIN mandate now in effect within Australia makes tipping via the"," ","receipt unsuitable. The function is still present on the API so existing integrations don't break,"," ","but it should be considered deprecated:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Method"},"children":["Method"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Description"},"children":["Description"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GetTipCompletionReference()"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Deprecated."]}," The tip completion reference. Only contains a value if the terminal processed a tipping transaction where the tip amount was to be written on the receipt."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Don't build new integrations against ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GetTipCompletionReference()"]}," — use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GetTipAmount()"]}," above."]}]},{"$$mdtype":"Tag","name":"div","attributes":{"label":"In-store API","disable":false},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["There's no request-time field for tipping — the applied tip amount is reported, read-only, in"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transactionOutcome.tipAmount"]}," on the"," ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/api-explorer/pay-in-person/0.9/pay-requests/get-pay-terminal-request"},"children":["Retrieve a pay request"]}," ","response once the transaction completes. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transactionOutcome.totalAmount"]}," includes the tip (and"," ","any surcharge)."]}]}]}]},"headings":[{"value":"Tipping","id":"tipping","depth":1},{"value":"Handling the response","id":"handling-the-response","depth":3},{"value":"Steps to follow","id":"steps-to-follow","depth":3},{"value":"Example response","id":"example-response","depth":4},{"value":"Demo","id":"demo","depth":3},{"value":"PIN-entry tipping (current)","id":"pin-entry-tipping-current","depth":3},{"value":"Tip completion (deprecated)","id":"tip-completion-deprecated","depth":3}],"frontmatter":{"title":"Tipping","seo":{"title":"Tipping"}},"lastModified":"2026-09-18T05:30:10.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/docs/in-person-payments/pay-in-person/features/tipping","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}