Integrated Bar-tabs

You are ready to start developing your Integrated Bar-tab 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 Bar-tab with Tyro.

Certification Criteria Document

Overview

The Integrated Bar-Tabs feature allows you to pre-authorise funds and keep tabs using your POS and EFTPOS without having to keep a customer’s credit card and ID document/s behind the bar. The feature allows customers to request bar-tabs with a set maximum amount, the staff opens a bartab on the POS with the chosen maximum amount, the bar-tab request is then initiated using the initiateOpenTab() function, and the cardholder secures the tab by tapping swiping or inserting their card on the Tyro terminal.

The POS is provided the response to the bar-tab request by iClient via the tranasctionCompleteCallback, with the the tab completion reference contained in the tabCompletionReference response field, the POS can then mark the tab off as secured, and the POS users can keep adding items/orders to the tab within the Bar-tab limit, the bar-tab can be closed off at any time for the amount used up using the closeTab() function with the completion reference included in the request. The bar-tab can also be voided if required, using the voidTab() function.

The main benefits of the Integrated Bar-tab feature are that there is no longer a need for patrons to leave their cards and ID documents behind the bar where they are open to theft or loss or skimming, not to mention that it is not a great user experience, the cardholder consequently does not have to wait until the end of the event to get their card back. There is no risk for the cardholder having the amount exceed their desired tab limit and no risk of the merchant not being settled the funds approved at the end of the event.

Important

The bar-tabs are automatically voided/reversed if not closed within 15 days.

info
  • The bar tab completion or void request does not involve the terminal, the request can be processed with the terminal disconnected or even powered off.
  • The Integrated Bar-Tabs feature is only available with credit cards (including scheme debit cards).

Open Tab Request

Function Definition Purpose Parameters
Boolean initiateOpenTab(requestParams , transactionCallbacks ) Initiates a request to open a bar-tab on the terminal. 1. requestParams (Object) - An object containing the following parameters as shown in the below table. 2. transactionCallbacks (Object) - The set of callback functions to provide feedback and the transaction result, please refer to the Transaction Callbacks section for more details.
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. Optional - Required for headless pairing, multi-merchant, or if your browser does not support local storage.
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. Optional - Required for headless pairing, multi-merchant, or if your browser does not support local storage.
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. Optional - Required for headless pairing, multi-merchart, or if your browser does not support local storage.
transactionId String Supply a transaction Id to be used for the transaction. Optional
Important

The bar-tabs are automatically voided/reversed if not closed within 15 days.

Please note
  • The bar tab completion or void request does not involve the terminal, the request can be processed with the terminal disconnected or even powered off.
  • The Integrated Bar-Tabs feature is only available with credit cards (including scheme debit cards).

Making the request | Open tab request

  • The POS sets the parameters that comprise the requestParams object as per the requirements of the specific transaction request, these parameters include the following:
    • amount - the amount is mandatory and the POS must declare it, please make sure that the amount is in cents and that the data type is String.
    • The integratedReceipt boolean to indicate whether the POS or the Tyro terminal is responsible for printing the receipts returned during the course of the transactions.Please note that the receipt data will not be returned to the POS if this is set to ‘false'.
  • The POS calls the initiateOpenTab(requestParams, transactionCallbacks) function with the requestParams included.
  • The POS must also reference the callback functions in the function invocation, the callback functions are responsible for handling the response, and are covered in more detail in the Response Handling section.

Request Example

Given below is an example request for a $100.0 integrated bar-tab request where the POS is printing the integrated receipts i.e. the receipts are being printed through the POS.

Copy
Copied
var amount = '10000';

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

}

Close Tab Request

Function Definition Purpose Parameters
Boolean closeTab(completionReference , amount , responseReceivedCallback ) Close a previously opened bar-tab with a final amount. The customer will be charged. 1. requestParams - An object containing the following parameters, as shown in the below table. 2. responseReceivedCallback (Object) - Invoked to indicate success or failure, please refer to the Response Handling section for more details.
Parameter Type Description Required
completionReference String Transaction identifier from the original open tab request. Required
amount String The amount that the tab is being closed for, maximum value can be the tab limit set in the open tab request (maximum amount to charge the customer) in cents. Required

Making the request | Close tab request

  • The POS sets the parameters that comprise the requestParams object as per the requirements of the specific transaction request, these parameters include the following:
    • amount - the amount is mandatory and the POS must declare it, please make sure that the amount is in cents and that the data type is String.
    • The TabCompletionReference boolean used from the Open Tab request which can be used to Close and Void a previously Opened Bar Tab
  • The POS calls the doCloseBarTab(amount, completionRefrence) function with the requestParams included.
  • The POS must also reference the callback functions in the function invocation, the callback functions are responsible for handling the response, and are covered in more detail in the Response Handling section.

Request Example

Given below is an example request for a $100.0 integrated bar-tab request where the POS is printing the integrated receipts i.e. the receipts are being printed through the POS.

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

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

Void Tab Request

Function Definition Purpose Parameters
Boolean voidTab(completionReference , responseReceivedCallback ) Void a previously opened bar tab, this discards the hold on funds in the customer's account. 1. requestParams - An object containing the following parameters, as shown in the below table. 2. responseReceivedCallback (Object) - Invoked to indicate success or failure, please refer to the section for more details.
Parameter Type Description Required
completionReference String Transaction identifier from the original open tab request. Required

Making the request | Void tab request

  • The POS sets the parameters that comprise the requestParams object as per the requirements of the specific transaction request, these parameters include the following:
    • The TabCompletionReference boolean used from the Open Tab request which can be used to Close and Void a previously Opened Bar Tab.
  • The POS calls the doVoidBarTab(completionRefrence) function with the requestParams included.
  • The POS must also reference the callback functions in the function invocation, the callback functions are responsible for handling the response, and are covered in more detail in the Response Handling section.

Request Example

Given below is an example request for a $ 100.0 integrated bar-tab request where the POS is printing the integrated receipts i.e. the receipts are being printed through the POS.

Copy
Copied
var completionReference = '12001';

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

Demo

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.

Please refer to the Transaction Callbacks section for handling the response.

Copyright © Tyro Payments 2019-2022. All right reserved.