Handling the response | Transaction Callbacks
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 |
Handling the response | Merchant Copy
A merchant copy is printed at the authorisation of each transaction. Merchant copies are optional (except those requiring a signature, see below) but you should assess if it is something your POS users would like to have or not. The merchant copy can be retrieved from the receiptCallback and should be printed immediately after it is returned.
Signature-Verification merchant copies
There are two types of merchant copies, those that require signature-verification and those that do not. The majority of transactions will not require a signature, since signature-verification has been gradually phased out since 2014, but there are a number of international cards that will still require a signature.
If the signature-verification is required to approve the transaction then a merchant copy with a signature line is printed, and the Tyro user-interface will ask the user if the the signature matches the one on the card. If they select ‘Yes' then the transaction will be completed and a customer copy is printed.
If they select ‘No’ then another merchant copy will be returned in the receiptCallback and printed showing the transaction was cancelled. The signature-verification merchant copy must be retained by the merchant for 120 days in case the cardholder initiates a charge-back in which case the merchant copy will need to be produced to show that the transaction was authorized by the cardholder.
Steps to follow
The steps involved in handling the response for merchant copies are as follows:
- Create the callback function to handle the callback response for the receiptCallback, the POS must undertake the required actions to print the receipts in the callback functions.
- The POS should check for the signatureRequired boolean in the callback response, if true it means that the receipt is a signature-verification merchant copy, is not optional, and must be printed.
- If the signatureRequired boolean is ‘false’ then the POS can choose to print the receipt depending on its merchant copy printing configuration
Signature-verification Merchant Copy 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
}
Merchant Copy (Not requiring signature) 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: XXXXXXXXX7002(s)\n
\n
Purchase AUD $100.00\n
----------\n
Total AUD $100.00\n
\n
APPROVED 00\n
\n
Terminal ID: 1\n
Transaction Ref: 116494\n
Authorisation No: N02109\n
03 Jan 2019 at 11:54 AM\n",
"signatureRequired":false
}
receiptCallback Implementation
Given below is an implementation for a receiptCallback, the function here is simply logging the receipt data to the console, and displaying it in a HTML element on screen.
var receiptCallbackImpl = function (receipt) {
console.log("Merchant Receipt = " + JSON.stringify(receipt));
$("#merchantReceipt").html(formatReceipt(receipt.merchantReceipt));
};
Transaction Complete Callback
Function | Description | Usage Required |
---|---|---|
transactionCompleteCallback | Invoked when the transaction has been completed on the terminal. Called with a customer receipt string field as part of the transactionData object as shown in the below | Required |
Field | Type | Description | Usage 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. | Required |
Handling the response | Customer Copy
Customer copies are printed on the completion of a transaction. They must be made available to the card holder for all transactions including unsuccessful transactions i.e. declined, cancelled, reversed, and system error.
You can retrieve the customer copy from the customerReceipt field of the transactionComplete Callback.
Steps to Follow
The steps involved in handling the customer copy response are given below:
- Obtain the pre-formatted customer copy receipt from the customerReceipt field in the callback function.
- Undertake all the steps required to manipulate the POS sales invoice and add the customer copy to the POS sales invoice.
- Print the integrated receipt.
transactionCompleteCallback Example
{
"result":"APPROVED",
"transactionId":"3783ea1cacae254808490fcf60bbd4eb221e",
"cardType":"MasterCard",
"transactionReference":"602145",
"authorisationCode":"031054",
"issuerActionCode":"00",
"elidedPan":"xxxxxxxxxxxx5100",
"rrn":"602145141255",
"tipAmount":"1000",
"baseAmount":"101.00",
"transactionAmount":"101.00",
"customerReceipt":
" CUSTOMER COPY \n
\n
Merchant 1655650 \n
Address line 1 \n
Address line 2 \n
\n
Tyro Payments EFTPOS \n
\n
MasterCard\n
Card: xxxxxxxxxxxx5100(s)\n
\n
Purchase AUD $100.00\n
Surcharge AUD $1.00\n
----------\n
Total AUD $101.00\n
\n
APPROVED 00\n
\n
Terminal ID: 8\n
Transaction Ref: 602145\n
Authorisation No: 031054\n
04 Jan 2019 at 02:12 PM\n"
}
transactionCompleteCallback Implementation Example
var transactionCompleteCallbackImpl = function (response) {
console.log("Response = " + JSON.stringify(response));
if (response.customerReceipt) {
console.log("Customer Receipt = " + JSON.stringify(response.customerReceipt));
$("#customerReceipt").html(formatReceipt(response.customerReceipt));
}
$("#result").html(formatResult(response));
};