Handling the response | Transaction Callbacks

The main development effort for POS partners using Tyro iClient is implementing the set of transaction callbacks. The integrated receipts feature in iClient involves the transactionCompleteCallback and the receiptCallback . The transactionCallbacks object provides these two callback functions to provide feedback for integrated receipts. The specification of relevant fields is given below:

Receipt Callback

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

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));
};