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.

Important

The pre-authorisations are automatically voided/reversed if not closed within 15 days

info

The pre-authorisation can also be voided if required, using the voidPreAuth() function. The pre-auth completion or void request does not involve the terminal, the request can be processed with the terminal disconnected or even powered off.

Open Pre-authorisation Request

Function Definition Purpose Parameters
Boolean initiateOpenPreAuth(requestParams , transactionCallbacks ) Initiates a request to open a pre-auth on the terminal. 1. requestParams - 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 pre-auth limit (The amount to set as the initial maximum amount for the pre-auth) 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

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';

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

Increment Pre-authorisation Request

Function Definition Purpose Parameters
Boolean initiateIncrementPreAuth(requestParams , transactionCallbacks ) Initiates a request to increment an already open pre-auth on the terminal. 1. requestParams (Object) - 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 Transaction Callbacks section for more details.
Parameter Type Description Required
completionReference String Transaction identifier from the original open pre-auth request. Required
amount String The amount is mandatory and the POS must declare it, please make sure that the amount is in cents 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

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.

Copy
Copied
var amt = '10000';
var ref = 12001

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

Complete Pre-authorisation Request

Function Definition Purpose Parameters
Boolean completePreAuth (requestParams responseReceivedCallback ) Close a previously opened pre-auth with a final amount. The customer will be charged. 1. requestParams - An object containing the following parameters. 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 pre-auth request. Required
amount String The amount that the pre-auth is being closed for, maximum value can be the pre-auth maximum amount after any successful increments added (maximum amount to charge the customer) in cents. Required

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.

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

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

Void Pre-authorisation Request

Function Definition Purpose Parameters
Boolean voidPreAuth(requestParams, responseReceivedCallback ) Void a previously opened pre-auth, 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 pre-auth request. Required

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.

Copy
Copied
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

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.

For handling the response, please refer to Transaction Callbacks

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