Integrated Pre-Authorisation

You are ready to start developing your Integrated Pre-Authorisation 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 pre-authorisation with Tyro.

Certification Criteria Document

Overview

The Integrated Pre-Authorisation feature allows you to pre-authorise funds and keep tabs using your POS and EFTPOS. The feature allows customers to request pre-authorised transactions with a set amount, the staff opens a pre-auth on the POS with the chosen amount, the pre-auth request is then initiated using the initiateOpenPreAuth() 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 pre-auth request by iClient via the tranasctionCompleteCallback, with the the tab completion reference contained in the preAuthCompletionReference response field, the POS can then mark the pre-auth off as secured, the POS users can increment the pre-auth using the initiateIncrementPreAuth() function, this will add the amount specified in the function to the open pre-authorisation. The pre-auth can also be closed off at any time, for up to the maximum amount using the closePreAuth() function with the completion reference and amount included in the completionReference and amount in the requestParams object of the request.

Open Pre-authorisation Request

Making the request | Open Pre-authorisation Request

The steps to be followed to initiate a Pre-auth are given as follows:

1. 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 (true or false) 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 is required to use the MID, integrationKey, and TID parameters if multi-merchant or headless pairing is used or if your browser does not support local storage.
   • transactionId - the POS can also choose to explcitly define a transaction ID to be used for end-to-end reporting in both systems (POS and Tyro system), this is completely optional, if this field is not set, the terminal chooses a transaction ID and assigns it to the transaction.
2. The POS calls the initiateOpenPreAuth(requestParams, transactionCallbacks) function with the requestParams included.
3. The POS must also reference the callback functions in the function invocation, the callback functions are responsible for handling the response.

Example

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

var amount = '10000';

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

Increment Pre-authorisation Request

Making the request | Increment Pre-authorisation Request

The steps to be followed to initiate a increment Pre-auth are given as follows:

1. The POS sets the parameters that comprise the requestParams object as per the requirements of the specific transaction request, these parameters include the following:
   • completionReference - Transaction identifier from the original open pre-auth request. Please make sure the data type is String.
   • 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 POS is required to use the MID, integrationKey, and TID parameters if multi-merchant or headless pairing is used or if your browser does not support local storage.
   • transactionId - the POS can also choose to explicitly define a transaction ID to be used for end-to-end reporting in both systems (POS and Tyro system), this is completely optional, if this field is not set, the terminal chooses a transaction ID and assigns it to the transaction.
2. The POS calls the initiateIncrementPreAuth(requestParams, transactionCallbacks) function with the requestParams included.
3. The POS must also reference the callback functions in the function invocation, the callback functions are responsible for handling the response.

Example

Given below is an example request for a $ 100.0 integrated increment pre-authorisation request.

var amt = '10000';
var ref = 12001

function doIncrementPreAuth(ref, amt){
requestParams = {amount: amt, completionReference: ref}
 iclient.initiateIncrementPreAuth(requestParams, responseReceivedCallbackImpl);
}

Complete Pre-authorisation Request

Making the request | Complete Pre-authorisation request

The steps to be followed to initiate a complete a Pre-auth request are given as follows:

1. The POS specifies the amount and the completion reference for the pre-auth in the amount and the completionReference parameters in the requestParams object of the completePreAuth function.
2. The POS is required to program the function required to handle the response payload delivered by the responseReceivedCallback and reference them in the function invocation correctly.

Example

Given below is an example request for a $100.00 integrated completePreAuth.

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

function doClosePreAuth(amount,completionReference)
 {
    iclient.completePreAuth({amount: amt, completionReference: ref}, responseReceivedCallbackImpl);
}

Void Pre-authorisation Request

Making the request | Void Pre-authorisation Request

The steps to be followed to initiate a void Pre-auth request are given as follows:

1. The POS specifies the amount and the completion reference for the voidPreAuth in the completionReference parameters in the requestParams object of the voidPreAuth function.
2. The POS is required to program the function required to handle the response payload delivered by the responseReceivedCallback and reference them in the function invocation correctly.

Example

Given below is an example request for a $100.00 integrated voidPreAuth request.

var completionReference = '12001';

function doVoidPreAuth(completionReference) {
requestParams = {completionReference:ref};
    iclient.voidPreAuth(requestParams, responseReceivedCallbackImpl);
}

Demo

Given below is a JS fiddle example that demonstrates the integrated pre-Auth feature, the Open pre-Auth request can be initiated using the pre-Auth limit specified, the pre-Auth can then be closed off with an amount that you specify in the field, or voided.

Demo - JS Fiddle

For handling the response, please refer to Transaction Callbacks