Bar tabs

Bar tabs let a POS pre-authorise funds and keep a tab running on the terminal, without holding a customer's card or ID document behind the bar. Staff open a tab on the POS with a chosen maximum amount; the cardholder secures it by tapping, swiping, or inserting their card on the terminal. The POS keeps adding items to the tab, then closes it off for the final amount used — which must not exceed the limit the tab was opened with — capturing the funds. A tab can also be voided, releasing the hold entirely.

This avoids the traditional "card behind the bar" approach: there's no risk of the card or ID being lost, stolen, or skimmed while out of the cardholder's sight, no need for the cardholder to wait until the end of the event to get their card back, no risk of the tab exceeding the limit they agreed to, and no risk of the merchant not being settled the funds approved at the end of the event.

A bar tab is automatically voided/reversed if it isn't closed within 15 days.

Closing or voiding a tab doesn't involve the terminal — it can be processed with the terminal disconnected or even powered off.
Bar tabs are only available with credit cards (including scheme debit cards).

Before you begin, check the certification criteria: Certification Criteria Document.

Making the request

Opening a tab

Function definition	Purpose	Parameters
`Boolean initiateOpenTab(requestParams, transactionCallbacks)`	Initiates a request to open a bar tab on the terminal.	`requestParams` (Object); `transactionCallbacks` (Object) — see Handling the response, below

Parameter	Type	Description	Required
`amount`	String	The tab limit (maximum amount to charge the customer) in cents.	Required
`integratedReceipt`	Boolean	Indicate whether receipts will be printed on the POS (`true`) or on the terminal (`false`).	Required
`mid`	Integer	Override the configured mid for multi-merchant terminals, or if your browser does not support local storage, or if you have developed headless pairing as a feature.	Conditional
`tid`	Integer	Override the configured tid for multi-merchant terminals or if your browser does not support local storage or if you have implemented headless pairing as a feature.	Conditional
`integrationKey`	String	Supply the integration key if your browser does not support local storage or if you have developed headless pairing or multi-merchant as a feature.	Conditional
`transactionId`	String	Supply a transaction ID to be used for the transaction.	Optional

mid, tid and integrationKey are required for headless pairing, for multi-merchant, or if your browser does not support local storage.

The POS sets the parameters that comprise the requestParams object as per the requirements of the request: amount is mandatory — declare it in cents, as a String — and integratedReceipt indicates whether the POS (true) or the terminal (false) is responsible for printing receipts; receipt data isn't returned to the POS if this is set to false. The POS then calls initiateOpenTab(requestParams, transactionCallbacks), referencing the callback functions that handle the response — covered in Handling the response, below.

A $100.00 bar tab request, with the POS printing the integrated receipts:

var amount = '10000';

function doBarTab(amount) {
    iclient.initiateOpenTab({
        amount: amount,
        integratedReceipt: true
    }, {
        receiptCallback: receiptCallbackImpl,
        transactionCompleteCallback: transactionCompleteCallbackImpl
    });

}

Closing a tab

Function definition	Purpose	Parameters
`Boolean closeTab(completionReference, amount, responseReceivedCallback)`	Closes a previously opened bar tab with a final amount — the customer is charged.	`responseReceivedCallback` (Function) — invoked to indicate success or failure

Parameter	Type	Description	Required
`completionReference`	String	Transaction identifier from the original open tab request.	Required
`amount`	String	The amount the tab is being closed for. Cannot exceed the tab limit set in the open tab request, in cents.	Required

The POS sets completionReference — the transaction identifier returned by the open tab request — and amount, the final amount in cents to charge, which cannot exceed the tab limit. The POS then calls closeTab(completionReference, amount, responseReceivedCallback), referencing the callback that handles the response — covered in Handling the response, below.

var amount = '10000';
var completionReference = '12001';

function doCloseBarTab(amount,completionReference) {
    iclient.closeTab(amount,completionReference, responseReceivedCallbackImpl);
}

Voiding a tab

Function definition	Purpose	Parameters
`Boolean voidTab(completionReference, responseReceivedCallback)`	Voids a previously opened bar tab — discards the hold on funds in the customer's account.	`responseReceivedCallback` (Function) — invoked to indicate success or failure

Parameter	Type	Description	Required
`completionReference`	String	Transaction identifier from the original open tab request.	Required

The POS sets completionReference — the transaction identifier returned by the open tab request — then calls voidTab(completionReference, responseReceivedCallback), referencing the callback that handles the response — covered in Handling the response, below.

var completionReference = '12001';

function doVoidBarTab(completionReference) {
    iclient.voidTab(completionReference, responseReceivedCallbackImpl);
}

JS Fiddle demo

Don't click Save if you make changes in the JS Fiddle — click Run instead. Clicking Save may break the fiddle's functionality.

Handling the response

Handling the response of the integrated bar tab functions in the JS library involves the use of the transactionCompleteCallback and the responseReceivedCallback.

Open tab response

Function	Description	Usage required
`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 indicates 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
`tabCompletionReference`	String	Tyro's reference to a Tab Completion.	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.	Conditional

customerReceipt is required if integrated receipt printing has been developed as a feature.

The response to the open tab request is returned to the POS by iClient using transactionCompleteCallback at the completion of the request.
If the request is successful, the POS is given the result and the tab completion reference in the result and tabCompletionReference fields — display the result for the user's reference and store the tab completion reference on the tab/sale invoice, to allow the tab to be closed off or voided later.
If the request is unsuccessful, the POS is given the result in the result field — display it for the user's reference.

var transactionCompleteCallbackImpl = function (response) {
    console.log(JSON.stringify(response));
    if (response.tabCompletionReference) {
   toggleClrResult();
        completionRef = response.tabCompletionReference;
        $("#tabRef").html(messageString + completionRef + "<br>" + "Tab Limit: " + parseFloat(amount/100));
        $("#closeTabBtn").removeClass("disabled");
        $("#voidTabBtn").removeClass("disabled");
    }
    if (response.customerReceipt) {
        $("#customerReceipt").html(formatReceipt(response.customerReceipt));
    }
    if (response.result!= "APPROVED"){
    var element = document.getElementById("tabRef");
        element.style.backgroundColor = "#ff3333";
    $("#tabRef").html("Open Tab Request not approved - please try again using the correct magic number");
    
    }
    $("#result").html(formatResult(response));
};

Example response

{
  "result": "APPROVED",
  "transactionId": "e378fb4c327daa4474d86aea89c9aabfe7c2",
  "cardType": "Visa",
  "transactionReference": "298143",
  "authorisationCode": "695585",
  "issuerActionCode": "00",
  "elidedPan": "XXXXXXXXXXXXXX8641",
  "rrn": "2981431109",
  "tabCompletionReference": "431721",
  "baseAmount": "102.00",
  "transactionAmount": "102.00",
  "customerReceipt": " CUSTOMER COPY \n\n Merchant 8811 \n Address line 1 \n Address line 2 \n\n Tyro EFTPOS \n\nVisa\nCard: XXXXXXXXXXXXXX8641(s)\n\nTab AUD $102.00\n\nAPPROVED 00\n\nA hold has been placed on\nyour account in the amount\nof $102.00. When the tab is\nclosed, up to $102.00 will\nbe debited from your\naccount.\n\nCompletion Ref: 431721\n\nTerminal ID: 123\nTransaction Ref: 298143\nAuthorisation No: 695585\n09 Nov 2021 at 08:59 PM\n"
}

Close tab response

Function	Description	Usage required
`responseReceivedCallback`	Invoked when the request has been completed on the terminal. Called with a single object containing the following fields.	Required

Field	Type	Description	Usage required
`result`	String	The result of the request, either `success` or `failure`.	Required
`message`	String	A message to display to the merchant.	Required

The response to the close tab request is returned to the POS by iClient using responseReceivedCallback at the completion of the request.
Whether successful or not, the POS is given the result and a message in the result and message fields — display them for the user's reference, and mark the tab as closed off if successful.

var responseReceivedCallbackImpl = function (response) {
    console.log(JSON.stringify(response));
    $("#result").html(formatResult(response));
    
    //Displaying the result in the div//
    if(response.message.includes("Close tab") && response.result=="success"){
    
      toggleClrResult("black");
     var element = document.getElementById("tabRef");
        element.style.backgroundColor = "#0A8D4F";
        element.style.color = "white";
    $("#tabRef").html("Tab reference "+ completionRef + " successfully closed for $" + tabCompletionAmount/100);

    }
    
    else if(response.message.includes("Void tab") && response.result=="success"){
        console.log("tab success")
         toggleClrResult("black");
        var element = document.getElementById("tabRef");
        element.style.backgroundColor = "#0A8D4F";
        element.style.color = "white";
    $("#tabRef").html("Tab reference "+ completionRef + " successfully voided");

    }
    
    else{
    toggleClrResult("red");
    }
    };

Example response

{
  "result": "success",
  "message": "Close tab request accepted"
}

Void tab response

Function	Description	Usage required
`responseReceivedCallback`	Invoked when the request has been completed on the terminal. Called with a single object containing the following fields.	Required

Field	Type	Description	Usage required
`result`	String	The result of the request, either `success` or `failure`.	Required
`message`	String	A message to display to the merchant.	Required

The response to the void tab request is returned to the POS by iClient using responseReceivedCallback at the completion of the request.
Whether successful or not, the POS is given the result and a message in the result and message fields — display them for the user's reference.

Void tab uses the same responseReceivedCallback handler shown above for Close tab — it branches on whether response.message contains "Close tab" or "Void tab" to tell the two apart.

Example response

{
  "result": "failure",
  "message": "Tab already closed"
}