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.
- 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.
| 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.) |
| 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 |
| 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.) |
| 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.) |
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.
Given below are examples of the 4 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> ");
$("#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));
};Given below is an example of the response returned for the transactionCompleteCallback
{
"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"
}Given below is an example of the response returned for the receiptCallback.
{
"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
}Given below is an example of the response returned for the statusMessageCallback.
{
"message": "Swipe card. Purchase: $100.00"
}Given below is an example of the response returned for the questionCallback.
{
"text": "APPROVED W/ SIGNATURE. Signature OK?",
"options": ["YES", "NO"]
}