{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-docs/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition","tabs","tab"]},"type":"markdown"},"seo":{"title":"Purchase, cashout and refund","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":"purchase-cashout-and-refund","__idx":0},"children":["Purchase, cashout and refund"]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Surcharging has been deprecated and will be retired by October 2026. All surcharging will be set"," ","to zero."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For new integrations (on or after 1 Oct 2026), Tyro recommends setting ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["enableSurcharge: false"]}," in"," ","all purchase requests. No action is required for existing integrations."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["These are the core in-person payment operations: a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["purchase"]}," charges the cardholder, optionally"," ","with ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["cashout"]}," (an additional cash amount dispensed alongside the purchase), and a ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["refund"]}," ","returns funds to a cardholder for a previous transaction."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"refund-rules","__idx":1},"children":["Refund rules"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["There can be no cashout associated with a refund."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["There can be no surcharge associated with a refund — the refund amount should already be"," ","inclusive of any surcharge applied to the original purchase. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/in-person-payments/pay-in-person/features/surcharge"},"children":["Surcharge"]}," for"," ","how each integration path reports the surcharge amount to use for this."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["There can be no HealthPoint claim transaction ID associated with a refund."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"headless-vs-ui-driven-integration","__idx":2},"children":["Headless vs. UI-driven integration"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Every integration path distinguishes between a default, Tyro-provided UI flow and a \"headless\""," ","mode where the POS drives its own UI and must handle terminal prompts and status updates directly."," ","The mechanism differs by platform — see the tabs below."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"related-features","__idx":3},"children":["Related features"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A purchase request can carry flags or fields that belong to other features documented separately:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/in-person-payments/pay-in-person/features/surcharge"},"children":["Surcharge"]}," — ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["enableSurcharge"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Tipping — reported on the transaction result, not a request flag"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/in-person-payments/pay-in-person/features/multi-merchant"},"children":["Multi-merchant"]}," — overriding the MID/TID/integration key on a per-transaction basis"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["HealthPoint claiming — paying off a claim's gap amount"]}]},{"$$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":"Heading","attributes":{"level":3,"id":"making-a-purchase-request","__idx":4},"children":["Making a purchase request"]},{"$$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 definition"},"children":["Function definition"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Purpose"},"children":["Purpose"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Parameters"},"children":["Parameters"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Required"},"children":["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":["Boolean initiatePurchase(requestParams, transactionCallbacks)"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Initiates a purchase transaction on the terminal."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["requestParams"]}," (Object); ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transactionCallbacks"]}," (Object) — see Handling the response, 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":"Parameter"},"children":["Parameter"]},{"$$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":"Required"},"children":["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":["amount"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["String"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The purchase amount (amount to charge the customer) in cents."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Required"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cashout"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["String"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Cash out amount in cents."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Conditional"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["integratedReceipt"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Boolean"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Indicate whether receipts will be printed on the POS (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]},") or on the terminal (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["false"]},")."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Required"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["mid"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Integer"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Override the configured mid for multi-merchant terminals, or if your browser does not support local storage, or if you have developed headless pairing as a feature."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Conditional"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tid"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Integer"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Override the configured tid for multi-merchant terminals or if your browser does not support local storage or if you have implemented headless pairing as a feature."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Conditional"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["integrationKey"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["String"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Supply the integration key if your browser does not support local storage or if you have developed headless pairing or multi-merchant as a feature."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Conditional"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transactionId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["String"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Supply a transaction ID to be used for the transaction. If not set, the terminal chooses one and assigns it to the transaction."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Optional"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["healthpointTransactionId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["String"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The integrated transaction ID of the original HealthPoint claim (used for gap payments)."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Conditional"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["enableSurcharge"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Boolean"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Apply a surcharge to this transaction (if the card used attracts a surcharge)."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Required"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Where a parameter is marked Conditional:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cashout"]}," is required only if cashout is being developed as a feature."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["mid"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tid"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["integrationKey"]}," are required for headless pairing, for multi-merchant, or if your browser does not support local storage."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["healthpointTransactionId"]}," is required only if Tyro HealthPoint has been developed as a feature."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Set ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["enableSurcharge"]}," to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]}," for every transaction unless the POS has its own surcharge feature, in which case a toggle is needed. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/in-person-payments/pay-in-person/features/surcharge"},"children":["Surcharge"]}," for the full toggle rule."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["More details on the multi-merchant feature can be found in the relevant section for multi-merchant"," ","— this is not a retail or hospitality feature, and is used predominantly in the health industry's"," ","Practice Management Software."]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"var amount = '1000';\n\nfunction doPurchase(amount) {\n    iclient.initiatePurchase({\n        amount: amount,\n        enableSurcharge: true,\n        integratedReceipt: false\n    }, {\n        receiptCallback: receiptCallbackImpl,\n        transactionCompleteCallback: transactionCompleteCallbackImpl\n    });\n}\n","lang":"javascript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"resuming-after-a-browser-refresh","__idx":5},"children":["Resuming after a browser refresh"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If the POS loses track of an in-progress or just-completed transaction — for example, the browser"," ","is refreshed or closed — iClient provides an optional ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["continueLastTransaction"]}," function that"," ","instructs the terminal to send the status update from the last transaction the POS initiated. Use"," ","it when the POS:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Lost track of the ongoing transaction — this resumes tracking from the transaction's current"," ","status on the terminal, so the result is still received and registered by the POS (avoiding a"," ","reconciliation mismatch with Tyro's reporting), and avoids error scenarios where the POS is"," ","left waiting for a response that will never arrive."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Needs to confirm the result of the previous transaction."]}]},{"$$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 definition"},"children":["Function definition"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Purpose"},"children":["Purpose"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Parameters"},"children":["Parameters"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["continueLastTransaction(transactionCallbacks)"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Instructs the terminal to send the status update from the last transaction."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transactionCallbacks"]}," (Object) — the same callbacks as above"]}]}]}]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"function doContinueLastTransaction()\n{\n    iclient.continueLastTransaction({\n        receiptCallback: receiptCallbackImpl,\n        transactionCompleteCallback: transactionCompleteCallbackImpl\n    });\n}\n","lang":"javascript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"making-a-refund-request","__idx":6},"children":["Making a refund request"]},{"$$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 definition"},"children":["Function definition"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Purpose"},"children":["Purpose"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Parameters"},"children":["Parameters"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Required"},"children":["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":["Boolean initiateRefund(requestParams, transactionCallbacks)"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Initiates a refund transaction on the terminal."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["requestParams"]}," (Object); ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transactionCallbacks"]}," (Object)"]},{"$$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":"Parameter"},"children":["Parameter"]},{"$$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":"Required"},"children":["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":["amount"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["String"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The refund amount in cents."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Required"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["integratedReceipt"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Boolean"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Indicate whether receipts will be printed on the POS (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]},") or on the terminal (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["false"]},")."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Required"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["mid"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Integer"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Override the configured mid for multi-merchant terminals, or if your browser does not support local storage, or if you have implemented headless pairing as a feature."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Optional"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tid"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Integer"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Override the configured tid for multi-merchant terminals or if your browser does not support local storage or if you have implemented headless pairing as a feature."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Optional"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["integrationKey"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["String"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Supply the integration key if your browser does not support local storage or if you have developed headless pairing or multi-merchant as a feature."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Optional"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transactionId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["String"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Supply a transaction ID to be used for the transaction."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Optional"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For a refund, the steps differ slightly: there can be no cashout, no surcharge (the"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["enableSurcharge"]}," flag must not be used), the refund amount should be inclusive of the surcharge"," ","applied to the original purchase, and there can be no HealthPoint transaction ID. Apart from that,"," ","the process is exactly the same as a purchase."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"var amount = '1000';\n\nfunction doRefund(amount) {\n    iclient.initiateRefund({\n        amount: amount,\n        integratedReceipt: false\n    }, {\n        receiptCallback: receiptCallbackImpl,\n        transactionCompleteCallback: transactionCompleteCallbackImpl\n    });\n}\n","lang":"javascript"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://jsfiddle.net/IntegrationSupport/qhmvnt9x/22/"},"children":["JS Fiddle demo"]}," — demonstrates purchase,"," ","refund, cashout, and a custom transaction ID; also demonstrates the \"Continue last transaction\""," ","function."]},{"$$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":"Heading","attributes":{"level":3,"id":"handling-the-response","__idx":7},"children":["Handling the response"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The purchase and refund functions involve a subset of the following callbacks, depending on"," ","whether headful or headless iClient is being used. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["statusMessageCallback"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["questionCallback"]}," ","are only used if headless iClient is being used for the development."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"transaction-complete-callback","__idx":8},"children":["Transaction complete callback"]},{"$$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 subset of the following parameters as part of the transactionData object."]},{"$$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":["result"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["String"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["One of: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["APPROVED"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CANCELLED"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["REVERSED"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DECLINED"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["SYSTEM ERROR"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["NOT STARTED"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["UNKNOWN"]},". The merchant will only receive money if this value is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["APPROVED"]},". ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["UNKNOWN"]}," means the merchant should look at the terminal to determine what happened — typically this indicates a network error."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Required"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cardType"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["String"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The scheme displayed on the card (Visa, Mastercard, etc)."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Optional"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transactionReference"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["String"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Also known as a STAN, this is Tyro's reference to this transaction. Quote this to Tyro Customer Support if you run into any issues with a transaction."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Optional"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["authorisationCode"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["String"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The scheme's reference to the transaction. Quote this number to Visa/Mastercard/etc if the issue is on their end."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Optional"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["issuerActionCode"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["String"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The raw result code returned by the card issuer."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Optional"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["elidedPan"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["String"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The (elided) card number used for this transaction."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Optional"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["rrn"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["String"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The Retrieval Reference Number is a unique number generated by the Payment Service for a specific merchant. Guaranteed to be unique for a 7-day period."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Optional"]}]},{"$$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":["If you are performing a Tip Completion, the tip component will be returned here, in cents."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Conditional"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tabCompletionReference"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["String"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Tyro's reference to a Tab Completion."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Conditional"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["preAuthCompletionReference"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["String"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Tyro's reference to a PreAuth Completion."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Conditional"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["baseAmount"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["String"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The value of the transaction in AUD cents (the amount for the transaction in the base currency)."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Optional"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transactionAmount"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["String"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The amount that is debited from the cardholder's account — may be in a foreign currency, e.g. for DCC transactions."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Optional"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["customerReceipt"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["String"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Text representation of the Tyro receipt intended for the customer. Only included if integrated receipt printing is enabled. Formatted to be printed in a monospaced font."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Conditional"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Where a field is marked Conditional, usage is required if the matching feature has been developed: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tipAmount"]}," for integrated tipping, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tabCompletionReference"]}," for integrated bar tabs, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["preAuthCompletionReference"]}," for integrated pre-auths, and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["customerReceipt"]}," for integrated receipt printing."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"receipt-callback","__idx":9},"children":["Receipt callback"]},{"$$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":["receiptCallback"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Invoked when integrated receipts are enabled and a merchant copy of the receipt is available. Ignored if integrated receipt printing is disabled. Called with the following parameters as part of the receipt object."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Conditional"]}]}]}]}]},{"$$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":["signatureRequired"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Boolean"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Indicates whether a signature line should be printed and a customer signature collected."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Required"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["merchantReceipt"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["String"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Text representation of the Tyro receipt intended for the merchant. Formatted to be printed in a monospaced font."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Required"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["receiptCallback"]}," is required if integrated receipts are enabled."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"status-message-callback","__idx":10},"children":["Status message callback"]},{"$$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":["statusMessageCallback"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Invoked to advertise what is happening on the terminal, which is typically facing the customer rather than the merchant. Called with a single String argument, for example \"Select account\"."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Conditional"]}]}]}]}]},{"$$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":["message"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["String"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Text representation of the current status of the transaction."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Conditional"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["statusMessageCallback"]}," is required only if using headless iClient, and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["message"]}," is required if the callback is being used."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"question-callback","__idx":11},"children":["Question callback"]},{"$$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":["questionCallback"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Invoked when the terminal requires the merchant to answer a question in order to proceed with the transaction. Called with the following parameters as part of the question object."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Conditional"]}]}]}]}]},{"$$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":["text"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["String"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The question message to present to the merchant."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Conditional"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["options"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Array[String]"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The set of button labels to present. A button should be presented to the merchant for each element in this array."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Conditional"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["answerCallback"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Function"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The callback to be used to provide the merchant's answer to the question. The POS should call this function when the merchant clicks one of the buttons, passing the label of the clicked button (from the options array in the question)."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Conditional"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["questionCallback"]}," is required only if using headless iClient. If the callback is being used, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["text"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["options"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["answerCallback"]}," are all required."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":4,"id":"steps-to-follow","__idx":12},"children":["Steps to follow"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Code callback functions to handle the responses returned by iClient via ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["statusMessageCallback"]},","," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["questionCallback"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transactionCompleteCallback"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Associate the callback functions you've created with the callbacks in the function invocation,"," ","as shown in the Making a purchase/refund request sections above."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use the response fields returned by the callback to control any subsequent workflows within the"," ","POS — e.g. using the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["result"]}," field to control when the POS closes the transaction off, displays"," ","the result on screen, and marks the transaction in the correct status, e.g. \"Approved\"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Conduct all follow-up actions/workflows in the callback function."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":5,"id":"callback-functions","__idx":13},"children":["Callback functions"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Given below are examples of the four callback functions created to handle the callback responses."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"javascript","header":{"controls":{"copy":{}}},"source":"function doPurchase(amount) {\n    iclient.initiatePurchase({\n        amount: amount,\n        cashout: \"0\",\n\t\tenableSurcharge: true,\n        integratedReceipt: true\n    }, {\n        statusMessageCallback: statusMessageCallbackImpl,\n        questionCallback: questionCallbackImpl,\n        receiptCallback: receiptCallbackImpl,\n        transactionCompleteCallback: transactionCompleteCallbackImpl\n    });\n}\n\nvar statusMessageCallbackImpl = function (message) {\n    console.log(\"Status is \" + JSON.stringify(message));\n    $(\"#statusMessage\").text(message);\n};\n\nvar questionCallbackImpl = function (question, answerCallback) {\n    console.log(\"Question is \" + JSON.stringify(question));\n    $(\"#statusMessage\").text(question.text);\n    $.each(question.options, function(index, option) {\n        console.log(\"Option \" + index + \" = \" + option);\n        $(\"#btns\").append(\"<button type=\\\"button\\\" id=\\\"btn\" + index + \"\\\" class=\\\"btn btn-sm btn-primary\\\">\" + option + \"</button>&nbsp;\");\n        $(\"#btn\" + index).click(function(){\n            $(\"#btns\").html(\"\");\n            answerCallback(option);\n        });\n    });\n};\n\nvar receiptCallbackImpl = function (receipt) {\n    $(\"#merchantReceipt\").html(formatReceipt(receipt.merchantReceipt));\n};\nvar transactionCompleteCallbackImpl = function (response) {\n    if (response.customerReceipt) {\n        $(\"#customerReceipt\").html(formatReceipt(response.customerReceipt));\n    }\n    $(\"#result\").html(formatResult(response));\n};\n","lang":"javascript"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":5,"id":"transactioncompletecallback-response-example","__idx":14},"children":["transactionCompleteCallback response example"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n\n\"result\":\"APPROVED\",\n\t\"transactionId\":\"10e850a33b061c44a18bc51acb05e0e6eb72\",\n\t\"cardType\":\"EFTPOS\",\n\t\"transactionReference\":\"160086\",\n\t\"authorisationCode\":\"F99047\",\n\t\"issuerActionCode\":\"08\",\n\t\"elidedPan\":\"XXXXXXX9953\",\n\t\"rrn\":\"0103160086\",\n\t\"baseAmount\":\"100.08\",\n\t\"transactionAmount\":\"100.08\",\n\t\"customerReceipt\":\n\t\t\"       CUSTOMER COPY       \\n\n\t\t\\n\n\t\t      Merchant 1655650      \\n\n\t\t       Address line 1       \\n\n\t\t       Address line 2       \\n\n\t\t\\n\n\t\t        Tyro EFTPOS         \\n\n\t\t\\n\n\t\tEFTPOS\\n\n\t\tCard: XXXXXXX9953(s)\\n\n\t\t\\n\n\t\tPurchase     AUD     $100.08\\n\n\t\t                  ----------\\n\n\t\tTotal        AUD     $100.08\\n\n\t\t\\n\n\t\tAPPROVED W/ SIGNATURE     08\\n\n\t\t\\n\n\t\tTerminal ID: 1\\n\n\t\tTransaction Ref: 160086\\n\n\t\tAuthorisation No: F99047\\n\n\t\t03 Jan 2019 at 11:56 AM\\n\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":5,"id":"receiptcallback-response-example","__idx":15},"children":["receiptCallback response example"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n\t\"merchantReceipt\":\n\t\t\"       MERCHANT COPY       \\n\n\t\t\\n\n\t\t      Merchant 1655650      \\n\n\t\t       Address line 1       \\n\n\t\t       Address line 2       \\n\n\t\t\\n\n\t\t        Tyro EFTPOS         \\n\n\t\t\\n\n\t\tEFTPOS\\n\n\t\tCard: XXXXXXX9953(s)\\n\n\t\t\\n\n\t\tPurchase     AUD     $100.00\\n\n\t\t                  ----------\\n\n\t\tTotal        AUD     $100.00\\n\n\t\t\\n\n\t\tAPPROVED W/ SIGNATURE     00\\n\n\t\t\\n\n\t\tTerminal ID: 1\\n\n\t\tTransaction Ref: 160086\\n\n\t\tAuthorisation No: F99047\\n\n\t\t03 Jan 2019 at 11:56 AM\\n\n\t\t\\n\n\t\t\\n\n\t\t----------------------------\\n\n\t\tSignature\\n\",\n\t\"signatureRequired\":true\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":5,"id":"statusmessagecallback-response-example","__idx":16},"children":["statusMessageCallback response example"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n\"message\": \"Swipe card. Purchase: $100.00\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":5,"id":"questioncallback-response-example","__idx":17},"children":["questionCallback response example"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n\"text\": \"APPROVED W/ SIGNATURE. Signature OK?\",\n\"options\": [\"YES\", \"NO\"]\n}\n","lang":"json"},"children":[]}]},{"$$mdtype":"Tag","name":"div","attributes":{"label":".NET library","disable":false},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The TTA's asynchronous interface returns control to the caller immediately after a request is"," ","submitted, and raises events as it has something to report. As of TTA v2, a headless capability"," ","(",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Tyro.Integ.ITerminalAdapterHeadless"]},") lets POS vendors implement their own UI instead of the"," ","default one — it has the same method signatures as the normal interface, plus extra methods and"," ","events for driving that UI."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["All methods are non-blocking. If a method is called while the Terminal Adapter is busy with"," ","another transaction, it returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["false"]},"; otherwise ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"methods-retail-and-hospitality","__idx":18},"children":["Methods (retail and hospitality)"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["boolean PurchaseAdditionalData(int amountInCents, int cashoutInCents, \"{ 'enableSurcharge': true | false }\")"]}," — commence a purchase transaction, signalling to a terminal (that is configured for surcharging) to include or exclude a surcharge. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/in-person-payments/pay-in-person/features/surcharge"},"children":["Surcharge"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["boolean PurchaseTransactionIdAdditionalData(int amountInCents, int cashoutInCents, String transactionId, \"{ 'enableSurcharge': true | false }\")"]}," — same, using a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transactionId"]}," generated by the POS."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["boolean Refund(int amountInCents)"]}," — commence a refund transaction. Returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["false"]}," if this instance of the Tyro Terminal Adapter is busy performing another transaction, or the amount is invalid."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["boolean Refund(int amountInCents, String transactionId)"]}," — same, using a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transactionId"]}," generated by the POS."]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transactionId"]},"s must be unique per transaction and be alpha-numeric only. This also applies to"," ","refunds, where a different ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transactionId"]}," must be used to refund a previous purchase. If the POS"," ","exits abnormally during a transaction, the POS can resume the current transaction by passing in the"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transactionId"]}," for the transaction it was processing — the TTA will either resume the transaction"," ","or provide the result of the transaction."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Multi-merchant terminals (predominantly a health-industry use case) use a separate set of"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["MidTid"]},"-suffixed methods — see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/in-person-payments/pay-in-person/features/multi-merchant"},"children":["Multi-merchant"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"events","__idx":19},"children":["Events"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Two kinds of events are raised: ones that can be raised multiple times during a transaction"," ","(only ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ReceiptReturned"]},"), and ones that are raised once, at the conclusion of a transaction."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ReceiptReturned"]}]}," — when there is a receipt available for printing. This event is raised only"," ","when printing via the POS is selected in the printing tab of the configuration menu. As many"," ","receipts per transaction may be produced, this event may be raised many times, and should be"," ","immediately printed by the POS.",{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GetText()"]}," — returns the text of the receipt, formatted only with spaces and newline characters."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["IsSignatureRequired()"]}," — an indication of whether a signature line should be added by the POS at the bottom of this receipt."]}]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TransactionCompleted"]}]}," — when the TTA has been given an indication by the terminal that the transaction has been completed.",{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GetStatus()"]}," — the status of the transaction, as a String. Can be either \"PENDING\" or \"COMPLETE\"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GetResult()"]}," — the result of this transaction, as a String. Can be either \"APPROVED\", \"DECLINED\", \"CANCELLED\", \"REVERSED\" or \"SYSTEM ERROR\". See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/in-person-payments/pay-in-person/integration-guide/net-library/api-reference#transaction-result-codes"},"children":["Transaction result codes"]}," for an interpretation guide."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GetReceipts()"]}," — a string array of all of the receipts for this transaction, in the order in which they were produced by the terminal. This will only be populated if \"Printing managed by the POS\" was enabled in the Printing tab of the Configuration dialog."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GetID()"]}," — the integrated transaction ID used in the transaction (used in combination with reconciliation)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GetCardType()"]}," — the card type used in this transaction. Currently \"EFTPOS\", \"Visa\", \"MasterCard\", \"American Express\", \"Diners Club\", \"JCB\", \"UnionPay\" or \"Afterpay\", but changes as new card types are accepted by Tyro."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GetAuthorisationCode()"]}," — the Authorisation Code for this transaction, as a String, from the issuer (if available — not always present)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GetTransactionReference()"]}," — the transaction reference, as a String, which together with the date and time of the transaction identifies this transaction within Tyro. This will only be populated if \"Printing managed by the POS\" was enabled in the Printing tab of the Configuration dialog."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GetTipAmount()"]}," — the tip amount that was keyed into the terminal during the transaction. See Tipping."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GetTipCompletionReference()"]}," — ",{"$$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. See Tipping."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GetCompletionReference()"]}," — the tab completion reference. The POS needs to store this value so that it can be used later on in the close tab completion process. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/in-person-payments/pay-in-person/features/bar-tabs"},"children":["Bar tabs"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GetExtraData()"]}," — returns an XML string with extra data, e.g. the surcharge amount — see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/in-person-payments/pay-in-person/features/surcharge"},"children":["Surcharge"]},"."]}]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ErrorOccurred"]}]}," — when there has been an error, either communicating with the integration"," ","server, or because of misconfiguration. When this is raised, the Terminal Adapter has no idea of"," ","the transaction result on the terminal, and the POS operator should be instructed to determine"," ","the status of the transaction by other means.",{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GetErrorMessage()"]}," — a plain English description of the error."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["IsTransactionStarted()"]}," — an indication of whether the Terminal Adapter has sent the request to commence the transaction. If this is false, then the POS operator does not need to be concerned with finding the final status of the transaction."]}]}]}]}]},{"$$mdtype":"Tag","name":"div","attributes":{"label":"In-store API","disable":false},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Start a transaction by"," ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/api-explorer/pay-in-person/0.9/pay-requests/create-pay-terminal-request"},"children":["creating a Pay Request"]},","," ","specifying ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["mid"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tid"]},", an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["origin"]}," (with a unique ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["orderId"]}," and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["transactionId"]},"), and a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["total"]}," ","(",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["goodsAndServicesAmount"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cashoutAmount"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["refundAmount"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["currency"]},"). Payments, payments with"," ","cashout, cashout-only, and refunds all use the same processing flow."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"mid\": \"123\",\n  \"tid\": \"456\",\n  \"origin\": {\n    \"orderId\": \"2e6174ae-ba4f-4a02-8072-9304d862e320\",\n    \"transactionId\": \"2e6174ae-ba4f-4a02-8072-9304d862e320\"\n  },\n  \"total\": {\n    \"goodsAndServicesAmount\": 1000,\n    \"cashoutAmount\": 500,\n    \"refundAmount\": 0,\n    \"currency\": \"AUD\"\n  }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["For the full lifecycle — tracking a Pay Request via notification events, answering terminal"," ","prompts, cancelling, rate limiting, and the nuances of terminal/network state — see"," ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/in-person-payments/pay-in-person/integration-guide/in-store-api/how-to-use"},"children":["How to use"]}," and"," ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/docs/in-person-payments/pay-in-person/integration-guide/in-store-api/error-codes"},"children":["Error codes"]},", which already cover this ground"," ","in detail for the In-store API as a whole."]}]}]}]},"headings":[{"value":"Purchase, cashout and refund","id":"purchase-cashout-and-refund","depth":1},{"value":"Refund rules","id":"refund-rules","depth":2},{"value":"Headless vs. UI-driven integration","id":"headless-vs-ui-driven-integration","depth":2},{"value":"Related features","id":"related-features","depth":2},{"value":"Making a purchase request","id":"making-a-purchase-request","depth":3},{"value":"Resuming after a browser refresh","id":"resuming-after-a-browser-refresh","depth":4},{"value":"Making a refund request","id":"making-a-refund-request","depth":3},{"value":"Handling the response","id":"handling-the-response","depth":3},{"value":"Transaction complete callback","id":"transaction-complete-callback","depth":4},{"value":"Receipt callback","id":"receipt-callback","depth":4},{"value":"Status message callback","id":"status-message-callback","depth":4},{"value":"Question callback","id":"question-callback","depth":4},{"value":"Steps to follow","id":"steps-to-follow","depth":4},{"value":"Callback functions","id":"callback-functions","depth":5},{"value":"transactionCompleteCallback response example","id":"transactioncompletecallback-response-example","depth":5},{"value":"receiptCallback response example","id":"receiptcallback-response-example","depth":5},{"value":"statusMessageCallback response example","id":"statusmessagecallback-response-example","depth":5},{"value":"questionCallback response example","id":"questioncallback-response-example","depth":5},{"value":"Methods (retail and hospitality)","id":"methods-retail-and-hospitality","depth":3},{"value":"Events","id":"events","depth":3}],"frontmatter":{"title":"Purchase, cashout and refund","seo":{"title":"Purchase, cashout and refund"}},"lastModified":"2026-10-18T02:32:40.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/docs/in-person-payments/pay-in-person/features/payment-cashout-refund","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}