Tyro terminals can be configured to support tipping as part of the transaction workflow — for hospitality locations, or anyone accepting gratuities. When enabled, the customer enters the tip amount they choose to pay directly into the terminal during the transaction workflow.
There are no extra steps for the POS to perform in terms of configuration or initiating the purchase request — there's no request parameter for tipping on any integration path. The terminal applies the tip amount automatically, and the applied amount is returned to the POS once the transaction completes.
The POS should:
- Display the tip amount clearly on the sales receipt, labelled "Tip".
- Include the tip amount in any POS reconciliation reports.
- Store the tip-inclusive amount on the sales invoice, so it's added back automatically on refund.
.NET library only: don't confuse this with "tip completion" (writing a tip amount on the receipt for the customer to fill in) — that's a deprecated legacy mechanism, unrelated to the PIN-entry tipping described here.
Before you begin, check the certification criteria: Certification Criteria Document.
There are no request parameters for tipping in initiatePurchase — the terminal handles it entirely, and the result is returned via transactionCompleteCallback.
The integrated tipping function only uses transactionCompleteCallback; the relevant fields are 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 transaction. | Required |
- 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 handled in the callback function.
- The POS must obtain the returned tip amount and display it clearly on the POS sales receipt, accurately labelled "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.
transactionCompleteCallback contains the applied tip amount in the tipAmount field, as shown in the example below.
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));
};A $100.00 purchase with a $10.00 tip and $1.00 surcharge:
{
"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"
}JS Fiddle demo — demonstrates tipping alongside surcharge, with merchant/customer copies printed and a "Refund last transaction" button.
The refund function returns an HTTP 400 "Invalid Transaction" error in this demo — expected, since tip-inclusive amounts aren't registered magic numbers for the integration simulator.
Don't click Save if you make changes in the JS Fiddle — click Run instead. Clicking Save may break the fiddle's functionality.