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:

  1. 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.
  2. 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
  3. 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”.
  4. 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"]
}
Support
Copyright © Tyro Payments 2019-2022. All right reserved.