Integrated Pre-Authorisation
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:
-
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.
- The POS calls the initiateOpenPreAuth(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.
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
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:
-
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.
- The POS calls the initiateIncrementPreAuth(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.
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
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:
- 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.
- 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
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:
- The POS specifies the amount and the completion reference for the voidPreAuth in the completionReference parameters in the requestParams object of the voidPreAuth function.
- 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.
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