Purchase, cashout and refund

Surcharging has been deprecated and will be retired by October 2026. All surcharging will be set to zero.

For new integrations (on or after 1 Oct 2026), Tyro recommends setting enableSurcharge: false in all purchase requests. No action is required for existing integrations.

These are the core in-person payment operations: a purchase charges the cardholder, optionally with cashout (an additional cash amount dispensed alongside the purchase), and a refund returns funds to a cardholder for a previous transaction.

Refund rules

There can be no cashout associated with a refund.
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 Surcharge for how each integration path reports the surcharge amount to use for this.
There can be no HealthPoint claim transaction ID associated with a refund.

Headless vs. UI-driven integration

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.

A purchase request can carry flags or fields that belong to other features documented separately:

Surcharge — enableSurcharge
Tipping — reported on the transaction result, not a request flag
Multi-merchant — overriding the MID/TID/integration key on a per-transaction basis
HealthPoint claiming — paying off a claim's gap amount

Before you begin, check the certification criteria: Certification Criteria Document.

Making a purchase request

Function definition	Purpose	Parameters	Required
`Boolean initiatePurchase(requestParams, transactionCallbacks)`	Initiates a purchase transaction on the terminal.	`requestParams` (Object); `transactionCallbacks` (Object) — see Handling the response, below	Required

Parameter	Type	Description	Required
`amount`	String	The purchase amount (amount to charge the customer) in cents.	Required
`cashout`	String	Cash out amount in cents.	Conditional
`integratedReceipt`	Boolean	Indicate whether receipts will be printed on the POS (`true`) or on the terminal (`false`).	Required
`mid`	Integer	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.	Conditional
`tid`	Integer	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.	Conditional
`integrationKey`	String	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.	Conditional
`transactionId`	String	Supply a transaction ID to be used for the transaction. If not set, the terminal chooses one and assigns it to the transaction.	Optional
`healthpointTransactionId`	String	The integrated transaction ID of the original HealthPoint claim (used for gap payments).	Conditional
`enableSurcharge`	Boolean	Apply a surcharge to this transaction (if the card used attracts a surcharge).	Required

Where a parameter is marked Conditional:

cashout is required only if cashout is being developed as a feature.
mid, tid and integrationKey are required for headless pairing, for multi-merchant, or if your browser does not support local storage.
healthpointTransactionId is required only if Tyro HealthPoint has been developed as a feature.

Set enableSurcharge to true for every transaction unless the POS has its own surcharge feature, in which case a toggle is needed. See Surcharge for the full toggle rule.

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.

var amount = '1000';

function doPurchase(amount) {
    iclient.initiatePurchase({
        amount: amount,
        enableSurcharge: true,
        integratedReceipt: false
    }, {
        receiptCallback: receiptCallbackImpl,
        transactionCompleteCallback: transactionCompleteCallbackImpl
    });
}

Resuming after a browser refresh

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 continueLastTransaction function that instructs the terminal to send the status update from the last transaction the POS initiated. Use it when the POS:

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.
Needs to confirm the result of the previous transaction.

Function definition	Purpose	Parameters
`continueLastTransaction(transactionCallbacks)`	Instructs the terminal to send the status update from the last transaction.	`transactionCallbacks` (Object) — the same callbacks as above

function doContinueLastTransaction()
{
    iclient.continueLastTransaction({
        receiptCallback: receiptCallbackImpl,
        transactionCompleteCallback: transactionCompleteCallbackImpl
    });
}

Making a refund request

Function definition	Purpose	Parameters	Required
`Boolean initiateRefund(requestParams, transactionCallbacks)`	Initiates a refund transaction on the terminal.	`requestParams` (Object); `transactionCallbacks` (Object)	Required

Parameter	Type	Description	Required
`amount`	String	The refund amount in cents.	Required
`integratedReceipt`	Boolean	Indicate whether receipts will be printed on the POS (`true`) or on the terminal (`false`).	Required
`mid`	Integer	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.	Optional
`tid`	Integer	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.	Optional
`integrationKey`	String	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.	Optional
`transactionId`	String	Supply a transaction ID to be used for the transaction.	Optional

For a refund, the steps differ slightly: there can be no cashout, no surcharge (the 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.

var amount = '1000';

function doRefund(amount) {
    iclient.initiateRefund({
        amount: amount,
        integratedReceipt: false
    }, {
        receiptCallback: receiptCallbackImpl,
        transactionCompleteCallback: transactionCompleteCallbackImpl
    });
}

JS Fiddle demo — demonstrates purchase, refund, cashout, and a custom transaction ID; also demonstrates the "Continue last transaction" function.

Don't click Save if you make changes in the JS Fiddle — click Run instead. Clicking Save may break the fiddle's functionality.

Handling the response

The purchase and refund functions involve a subset of the following callbacks, depending on whether headful or headless iClient is being used. statusMessageCallback and questionCallback are only used if headless iClient is being used for the development.

Transaction complete callback

Function	Description	Usage required
`transactionCompleteCallback`	Invoked when the transaction has been completed on the terminal. Called with a subset of the following parameters as part of the transactionData object.	Required

Field	Type	Description	Usage required
`result`	String	One of: `APPROVED`, `CANCELLED`, `REVERSED`, `DECLINED`, `SYSTEM ERROR`, `NOT STARTED`, `UNKNOWN`. The merchant will only receive money if this value is `APPROVED`. `UNKNOWN` means the merchant should look at the terminal to determine what happened — typically this indicates a network error.	Required
`cardType`	String	The scheme displayed on the card (Visa, Mastercard, etc).	Optional
`transactionReference`	String	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.	Optional
`authorisationCode`	String	The scheme's reference to the transaction. Quote this number to Visa/Mastercard/etc if the issue is on their end.	Optional
`issuerActionCode`	String	The raw result code returned by the card issuer.	Optional
`elidedPan`	String	The (elided) card number used for this transaction.	Optional
`rrn`	String	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.	Optional
`tipAmount`	String	If you are performing a Tip Completion, the tip component will be returned here, in cents.	Conditional
`tabCompletionReference`	String	Tyro's reference to a Tab Completion.	Conditional
`preAuthCompletionReference`	String	Tyro's reference to a PreAuth Completion.	Conditional
`baseAmount`	String	The value of the transaction in AUD cents (the amount for the transaction in the base currency).	Optional
`transactionAmount`	String	The amount that is debited from the cardholder's account — may be in a foreign currency, e.g. for DCC transactions.	Optional
`customerReceipt`	String	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.	Conditional

Where a field is marked Conditional, usage is required if the matching feature has been developed: tipAmount for integrated tipping, tabCompletionReference for integrated bar tabs, preAuthCompletionReference for integrated pre-auths, and customerReceipt for integrated receipt printing.

Receipt callback

Function	Description	Usage required
`receiptCallback`	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.	Conditional

Field	Type	Description	Usage required
`signatureRequired`	Boolean	Indicates whether a signature line should be printed and a customer signature collected.	Required
`merchantReceipt`	String	Text representation of the Tyro receipt intended for the merchant. Formatted to be printed in a monospaced font.	Required

receiptCallback is required if integrated receipts are enabled.

Status message callback

Function	Description	Usage required
`statusMessageCallback`	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".	Conditional

Field	Type	Description	Usage required
`message`	String	Text representation of the current status of the transaction.	Conditional

statusMessageCallback is required only if using headless iClient, and message is required if the callback is being used.

Question callback

Function	Description	Usage required
`questionCallback`	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.	Conditional

Field	Type	Description	Usage required
`text`	String	The question message to present to the merchant.	Conditional
`options`	Array[String]	The set of button labels to present. A button should be presented to the merchant for each element in this array.	Conditional
`answerCallback`	Function	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).	Conditional

questionCallback is required only if using headless iClient. If the callback is being used, text, options and answerCallback are all required.

Steps to follow

Code callback functions to handle the responses returned by iClient via statusMessageCallback, questionCallback, and transactionCompleteCallback.
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.
Use the response fields returned by the callback to control any subsequent workflows within the POS — e.g. using the 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".
Conduct all follow-up actions/workflows in the callback function.

Callback functions

Given below are examples of the four callback functions created to handle the callback responses.

function doPurchase(amount) {
    iclient.initiatePurchase({
        amount: amount,
        cashout: "0",
		enableSurcharge: true,
        integratedReceipt: true
    }, {
        statusMessageCallback: statusMessageCallbackImpl,
        questionCallback: questionCallbackImpl,
        receiptCallback: receiptCallbackImpl,
        transactionCompleteCallback: transactionCompleteCallbackImpl
    });
}

var statusMessageCallbackImpl = function (message) {
    console.log("Status is " + JSON.stringify(message));
    $("#statusMessage").text(message);
};

var questionCallbackImpl = function (question, answerCallback) {
    console.log("Question is " + JSON.stringify(question));
    $("#statusMessage").text(question.text);
    $.each(question.options, function(index, option) {
        console.log("Option " + index + " = " + option);
        $("#btns").append("<button type=\"button\" id=\"btn" + index + "\" class=\"btn btn-sm btn-primary\">" + option + "</button>&nbsp;");
        $("#btn" + index).click(function(){
            $("#btns").html("");
            answerCallback(option);
        });
    });
};

var receiptCallbackImpl = function (receipt) {
    $("#merchantReceipt").html(formatReceipt(receipt.merchantReceipt));
};
var transactionCompleteCallbackImpl = function (response) {
    if (response.customerReceipt) {
        $("#customerReceipt").html(formatReceipt(response.customerReceipt));
    }
    $("#result").html(formatResult(response));
};

transactionCompleteCallback response example

{

"result":"APPROVED",
	"transactionId":"10e850a33b061c44a18bc51acb05e0e6eb72",
	"cardType":"EFTPOS",
	"transactionReference":"160086",
	"authorisationCode":"F99047",
	"issuerActionCode":"08",
	"elidedPan":"XXXXXXX9953",
	"rrn":"0103160086",
	"baseAmount":"100.08",
	"transactionAmount":"100.08",
	"customerReceipt":
		"       CUSTOMER COPY       \n
		\n
		      Merchant 1655650      \n
		       Address line 1       \n
		       Address line 2       \n
		\n
		        Tyro EFTPOS         \n
		\n
		EFTPOS\n
		Card: XXXXXXX9953(s)\n
		\n
		Purchase     AUD     $100.08\n
		                  ----------\n
		Total        AUD     $100.08\n
		\n
		APPROVED W/ SIGNATURE     08\n
		\n
		Terminal ID: 1\n
		Transaction Ref: 160086\n
		Authorisation No: F99047\n
		03 Jan 2019 at 11:56 AM\n"
}

receiptCallback response example

{
	"merchantReceipt":
		"       MERCHANT COPY       \n
		\n
		      Merchant 1655650      \n
		       Address line 1       \n
		       Address line 2       \n
		\n
		        Tyro EFTPOS         \n
		\n
		EFTPOS\n
		Card: XXXXXXX9953(s)\n
		\n
		Purchase     AUD     $100.00\n
		                  ----------\n
		Total        AUD     $100.00\n
		\n
		APPROVED W/ SIGNATURE     00\n
		\n
		Terminal ID: 1\n
		Transaction Ref: 160086\n
		Authorisation No: F99047\n
		03 Jan 2019 at 11:56 AM\n
		\n
		\n
		----------------------------\n
		Signature\n",
	"signatureRequired":true
}

statusMessageCallback response example

{
"message": "Swipe card. Purchase: $100.00"
}

questionCallback response example

{
"text": "APPROVED W/ SIGNATURE. Signature OK?",
"options": ["YES", "NO"]
}