Handling the response | Transaction Callbacks

The main development effort for POS partners using Tyro iClient is implementing the set of transaction callbacks. The purchase and refund functions in iClient involve a subset of the following set of callbacks depending on whether Headful iClient or Headless iClient is being used.

The transactionCallbacks object provides the set of callback functions to provide feedback, receipts, and the transaction result.

The following callback functions are available:

transactionCompleteCallback
receiptReceivedCallback
statusMessageCallback
questionCallback

Please Note:

The statusMessageCallback and the questionCallback are only used if headless iClient is being used for the development.

The specification for each of the callbacks is given in the respective tables.

Transaction Complete Callback

Function	Description	Usage
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 the following values: 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 would indicate 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) credit 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.	Optional (Usage required if Integrated Tipping has been developed as a feature.)
tabCompletionReference	String	Tyro's reference to a Tab Completion.	Optional (Usage required if Integrated Bar tabs has been developed as a feature.)
preAuthCompletionReference	String	Tyro's reference to a PreAuth Completion.	Optional (Usage required if Integrated Pre-auths have been developed as a feature.)
baseAmount	String	The value of the transaction in AUD.	Optional (The amount for the transaction in the base currency.)
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.	Optional (Usage required if Integrated receipt printing has been developed as a feature.)

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.	REQUIRED (If integrated receipts are enabled.)

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

Status message Callback

Function	Description	Usage Required
statusMessageCallback	Invoked to advertise what is happening on terminal, which is typically facing the customer rather than the merchant. Called with a single String argument. For example "Select account".	Optional (Only required if using Headless iClient.)

Field	Type	Description	Usage Required
message	String	Text representation of the current status of the transaction.	Required (if the callback itself 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	Optional (Only required if using Headless iClient.)

Field	Type	Description	Usage Required
text	String	The question message to present to the merchant.	Required (if the callback itself is being used.)
options	Array[String]	The set of button labels to present. A button should be presented to the merchant for each element in this array.	Required (if the callback itself is being used.)
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).	Required (if the callback itself is being used.)

Steps to follow

The steps to be followed to handle the response for an integrated purchase or refund transaction are given as follows:

You are required to code callback functions to handle the responses returned by iClient via the statusMessageCallback , the questionCallback , and the transactionCompleteCallback . Examples of callback functions are given in the below sections.
You must associate the callback functions that you have created with the callbacks in the function invocation as shown in the examples in the Making the Request section of Integrated Purchase, Cashout and Refund
The POS must use the response fields returned by the callback, and use them 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 the screen, and mark the transaction in the correct status e.g. “Approved”.
The POS must conduct all follow-up actions/workflows in the callback function.

Please Note:

The statusMessageCallback and the questionCallback are only used if headless iClient is being used for the development.

Callback Functions

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

Copy

Copied

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

Given below is an example of the response returned for the transactionCompleteCallback

Copy

Copied

{

"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

Given below is an example of the response returned for the receiptCallback.

Copy

Copied

{
	"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:

Given below is an example of the response returned for the statusMessageCallback.

Copy

Copied

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

questionCallback Response Example:

Given below is an example of the response returned for the questionCallback.

Copy

Copied

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