Integrated Tipping

You are ready to start developing your integrated tipping feature now that you have successfully setup your POS to initiate and process requests through iClient in the test environment. Before you begin, please have a look at the certification criteria, which provide a checklist of the minimum requirements for the certification of integrated tipping with Tyro.

Certification Criteria Document

Overview

The Tyro terminals can be configured to support tipping as part of the transaction workflow for hospitality locations or for anyone that wants to accept gratuities. When tipping is enabled on the Tyro terminal, the customer can enter the tip amount that they choose to pay into the terminal during the transaction workflow.

Important

There are no extra steps that have to be performed by the POS in terms of configuration or initiating the purchase request, there are no request parameters in the purchase function that pertain to tipping.

The terminal will apply the tip amount automatically as part of the transaction, and upon successful completion of the transaction the Tyro iClient will return the applied tip amount back to the POS as part of the transaction response in the tipAmount field of the transactionCompleteCallback. The POS can then use the tip amount to include it on the POS sales receipt, any POS reconciliation reports developed, and store it on the sales invoice for automatic addition of the tip back onto the refund.

Demo

Given below is a JS fiddle example that demonstrates the integrated tipping feature, the merchant copy and integrated receipt are printed out, the integrated receipt clearly shows the surcharge amount, and the “Refund Last Transaction“ button can be used to initiate a refund of the last processed purchase transaction with the surcharge-inclusive amount.

info

Please note that the refund function will return a HTTP 400 “Invalid Transaction” details error message, this is expected behavior since the tip-inclusive amounts are not registered magic numbers for the integration simulator.

Demo - JS Fiddle

JS Fiddle

Please don't click on the Save button if you make any changes in the JS Fiddle sample app. Instead, please press run if you have made any changes. If you click on save, it may break the functionality of the JS Fiddle.

Handling the response | Transaction Complete Callback

The integrated tipping function only entails the use of the transactionCompleteCallback only, the specification of the relevant fields is given below:

Function	Description	Usage Required
transactionCompleteCallback	Invoked when the transaction has been completed on the terminal. Called with a tip amount string field as part of the transactionData object as shown below.	Required

Field	Type	Description	Usage Required
tipAmount	String	The applied tip amount for the given transaction.	Required

Steps to follow

The steps to follow in handling the response are as given below:

The applied tip amount is returned to the POS in the transaction response. The POS must specify any and all actions pertaining to how the tip amount is being handled in the callback function.
The POS must obtain the returned tip amount and display it clearly on the POS sales receipt accurately labelled as 'Tip', the POS must also store the tip-inclusive amount for the transaction on the sales invoice so that when refunded, the tip amount is automatically added back on without any manual intervention.

The transactionCompleteCallback contains the applied tip amount in the tipAmount field, as shown in the below example.

transactionCompleteCallback function

Copy

Copied

var transactionCompleteCallbackImpl = function (response) {
    console.log("Response = " + JSON.stringify(response));
		var tip=response.tipAmount/100;
    if (response.customerReceipt) {

        console.log("Customer Receipt = " + JSON.stringify(response.customerReceipt));

//Compiling the integrated receipt:
if(transactionType=="purchase" && response.result=="APPROVED"){
    total = ($("#amount").val()/ 100);
		totalamount = total+tip;
    console.log(totalamount);
var posReceipt = formatReceipt("\tTAX INVOICE       \r\n\r\n      Merchant 1655650     \r\n      Address line 1       \r\n      Address line 2       \r\n\r\n\tAWESOME POS   \r\n\t\r\nItems\t\t\t$\r\nCoffee\t\t\t" + "$"+total + "\r\n\t\r\nSub-total\t\t" + "$"+total + "\r\n\r\nTip\t\t\t"+ "$"+ tip + "\r\n\r\nTotal\t\t\t"+ "$"+(total+tip) +"\r\n\r\nGST inc\t\t\t$1.00\r\n\r\nPOS ID: 2\r\nRef: 12345abc\r\n04 Jan 2019 at 02:12 PM\r\n\n\n\t--------------------\n\n" + response.customerReceipt);
        
        console.log(posReceipt);

        $("#customerReceipt").html(posReceipt);
				
}
else if(transactionType=="refund" && response.result=="APPROVED"){
console.log(transactionType);
 var posReceipt = formatReceipt("\tTAX INVOICE       \r\n\r\n      Merchant 1655650     \r\n      Address line 1       \r\n      Address line 2       \r\n\r\n\tAWESOME POS   \r\n\t\r\nREFUND\t\t\t$\r\nAmount\t\t\t" + "$"+total + "\r\n\t\r\nSub-total\t\t" + "$"+total   +"\r\n\r\nTotal\t\t\t"+ "$"+total +"\r\n\r\nGST inc\t\t\t$1.00\r\n\r\nPOS ID: 2\r\nRef: 12345abc\r\n04 Jan 2019 at 02:12 PM\r\n\n\n\t--------------------\n\n" + response.customerReceipt);

        
        console.log(posReceipt);

        $("#customerReceipt").html(posReceipt);
}

else{
console.log(transactionType);
 var posReceipt = formatReceipt("\t AWESOME POS      \r\n\r\n      Merchant 1655650     \r\n      Address line 1       \r\n      Address line 2       \r\n\r\n\tAWESOME POS   \r\n\t\r\nTRANSACTION FAILED\t\t\r\nResult:\t\t\t" + response.result + "\r\n\r\nPOS ID: 2\r\nRef: 12345abc\r\n04 Jan 2019 at 02:12 PM\r\n\n\n\t--------------------\n\n" + response.customerReceipt);
        
        console.log(posReceipt);

        $("#customerReceipt").html(posReceipt);

}

       
}
    $("#result").html(formatResult(response));
};

Callback Response

Given below is an example request for a $ 100.0 purchase transaction with $10.00 tip and $1.00 surcharge.

Copy

Copied

{
"result":"APPROVED",
"transactionId":"3783ea1cacae254808490fcf60bbd4eb221e",
"cardType":"MasterCard",
"transactionReference":"602145",
"authorisationCode":"031054",
"issuerActionCode":"00",
"elidedPan":"xxxxxxxxxxxx5100",
"rrn":"602145141255",
"tipAmount":"10.00",
"surchargeAmount":"1.00",
"baseAmount":"111.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
	Tip    		 AUD       $10.00\n
                  ----------\n
	Total        AUD     $111.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"
}