Handling the response | Transaction Callbacks

Handling the response of the integrated bar tab functions in iClient involves the use of the transactionCompleteCallback and the responseReceivedCallback.

Transaction Complete Callback | Open Tab Request

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, as shown in the below table.	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
tabCompletionReference	String	Tyro's reference to a Tab Completion.	Required
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.

Handling the response | Open Tab Request

The steps to be followed to handle the response for the open tab request are as given below:

The response to the open tab request is returned to the POS by iClient using the transactionCompleteCallback at the completion of the open tab request. The POS must program the function needed to handle this response.
If the request is successful, the POS will be provided the result, and the tab completion reference in the result and the tabCompleteionReference fields, the POS must use them, and display the result for the user’s reference and store the tab completion reference on the tab/sale invoice to allow the tab to be closed off or voided.
If the request is unsuccessful, the POS will be provided the result in the result and the tabCompleteionReference fields, the POS must use it and display the result for the user’s reference.

Callback Function

Given below is an example of a callback function created to handle the response.

Copy

Copied

var transactionCompleteCallbackImpl = function (response) {
    console.log(JSON.stringify(response));
    if (response.tabCompletionReference) {
   toggleClrResult();
        completionRef = response.tabCompletionReference;
        $("#tabRef").html(messageString + completionRef + "<br>" + "Tab Limit: " + parseFloat(amount/100));
        $("#closeTabBtn").removeClass("disabled");
        $("#voidTabBtn").removeClass("disabled");
    }
    if (response.customerReceipt) {
        $("#customerReceipt").html(formatReceipt(response.customerReceipt));
    }
    if (response.result!= "APPROVED"){
    var element = document.getElementById("tabRef");
        element.style.backgroundColor = "#ff3333";
    $("#tabRef").html("Open Tab Request not approved - please try again using the correct magic number");
    
    }
    $("#result").html(formatResult(response));
};

transactionCompleteCallback Response

Copy

Copied

{
  "result": "APPROVED",
  "transactionId": "e378fb4c327daa4474d86aea89c9aabfe7c2",
  "cardType": "Visa",
  "transactionReference": "298143",
  "authorisationCode": "695585",
  "issuerActionCode": "00",
  "elidedPan": "XXXXXXXXXXXXXX8641",
  "rrn": "2981431109",
  "tabCompletionReference": "431721",
  "baseAmount": "102.00",
  "transactionAmount": "102.00",
  "customerReceipt": " CUSTOMER COPY \n\n Merchant 8811 \n Address line 1 \n Address line 2 \n\n Tyro EFTPOS \n\nVisa\nCard: XXXXXXXXXXXXXX8641(s)\n\nTab AUD $102.00\n\nAPPROVED 00\n\nA hold has been placed on\nyour account in the amount\nof $102.00. When the tab is\nclosed, up to $102.00 will\nbe debited from your\naccount.\n\nCompletion Ref: 431721\n\nTerminal ID: 123\nTransaction Ref: 298143\nAuthorisation No: 695585\n09 Nov 2021 at 08:59 PM\n"
}

Response Received Callback | Close Tab Request

Function	Description	Usage Required
responseReceivedCallback	Invoked when the request has been completed on the terminal. Called with a single object containing the following fields, as shwon in the below table.	Required

Field	Type	Description	Usage Required
result	String	The result of the request, will be either ‘success’ or ‘failure’.	Required
message	String	A message to display to the merchant.	Required

Handling the response | Close Tab Request

The steps to be followed to handle the response for the close tab request are as given below:

The response to the close tab request is returned to the POS by iClient using the responseReceivedCallback at the completion of the close tab request. The POS must program the function to be used to handle the callback response.
If the request is successful, the POS will be provided the result, and an additional message in the result and the message fields, the POS must use them, and display the result and the message for the user’s reference and mark the tab as closed off.
If the request is unsuccessful, the POS will be provided the result, and an additional message in the result and the message fields, the POS must use them, and display the result and the message for the user’s reference.

Callback Function

Given below is an example of a function created to handle the callback response.

Copy

Copied

var responseReceivedCallbackImpl = function (response) {
    console.log(JSON.stringify(response));
    $("#result").html(formatResult(response));
    
    //Displaying the result in the div//
    if(response.message.includes("Close tab") && response.result=="success"){
    
      toggleClrResult("black");
     var element = document.getElementById("tabRef");
        element.style.backgroundColor = "#0A8D4F";
        element.style.color = "white";
    $("#tabRef").html("Tab reference "+ completionRef + " successfully closed for $" + tabCompletionAmount/100);

    }
    
    else if(response.message.includes("Void tab") && response.result=="success"){
        console.log("tab success")
         toggleClrResult("black");
        var element = document.getElementById("tabRef");
        element.style.backgroundColor = "#0A8D4F";
        element.style.color = "white";
    $("#tabRef").html("Tab reference "+ completionRef + " successfully voided");

    }
    
    else{
    toggleClrResult("red");
    }
    };

responseReceivedCallback Response

Given below is an example of a sample response payload for the response received callback.

Copy

Copied

{
  "result": "success",
  "message": "Close tab request accepted"
}

Response Received Callback | Void Tab Request

Function	Description	Usage Required
responseReceivedCallback	Invoked when the request has been completed on the terminal. Called with a single object containing the following field, as shown in the below table.	Required

Field	Type	Description	Usage Required
result	String	The result of the request, will be either ‘success’ or ‘failure’.	Required
message	String	A message to display to the merchant.	Required

Handling the response | Void Tab Request

The steps to be followed to handle the response for the close tab request are as given below:

The response to the void tab request is returned to the POS by iClient using the responseReceivedCallback at the completion of the close tab request. The POS must program the function to be used to handle the callback response.
If the request is successful, the POS will be provided the result, and an additional message in the result and the message fields, the POS must use them, and display the result and the message for the user’s reference and mark the tab as closed off.
If the request is unsuccessful, the POS must use them, and display the result and the message for the user’s reference.

responseReceivedCallback

Given below is an example of a sample response payload for the response received callback.

Copy

Copied

var responseReceivedCallbackImpl = function (response) {
    console.log(JSON.stringify(response));
    $("#result").html(formatResult(response));
    
    //Displaying the result in the div//
    if(response.message.includes("Close tab") && response.result=="success"){
    
      toggleClrResult("black");
     var element = document.getElementById("tabRef");
        element.style.backgroundColor = "#0A8D4F";
        element.style.color = "white";
    $("#tabRef").html("Tab reference "+ completionRef + " successfully closed for $" + tabCompletionAmount/100);

    }
    
    else if(response.message.includes("Void tab") && response.result=="success"){
        console.log("tab success")
         toggleClrResult("black");
        var element = document.getElementById("tabRef");
        element.style.backgroundColor = "#0A8D4F";
        element.style.color = "white";
    $("#tabRef").html("Tab reference "+ completionRef + " successfully voided");

    }
    
    else{
    toggleClrResult("red");
    }
    };

responseReceivedCallback Response

Given below is an example of a sample response payload for the response received callback.

Copy

Copied

{
  "result": "failure",
  "message": "Tab already closed"
}