Pre-authorisation

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

Opening a pre-auth

Making the 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:
   • amount — the amount is mandatory and the POS must declare it; 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. 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.
2. The POS calls initiateOpenPreAuth(requestParams, transactionCallbacks) 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.00 integrated open pre-auth request where the POS is printing the integrated receipts, i.e. the receipts are being printed through the POS.

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

Handling the response

The response to the open pre-authorisation request is returned to the POS by iClient using transactionCompleteCallback at the completion of the open pre-auth request. If the request is successful, the POS will be provided the result and the preAuthCompletionReference field, along with other relevant fields. The POS must display the result for the user's reference and store the pre-auth completion reference in the sale invoice to allow the pre-auth to be closed off or voided.

Response example

{
  "result": "APPROVED",
  "transactionId": "e378fb4c327daa4474d86aea89c9aabfe7c2",
  "cardType": "Visa",
  "transactionReference": "298143",
  "authorisationCode": "695585",
  "issuerActionCode": "00",
  "elidedPan": "XXXXXXXXXXXXXX8641",
  "rrn": "2981431109",
  "preAuthCompletionReference": "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\nPreAuth 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"
}

Incrementing a pre-auth

Making the request

The steps to be followed to initiate an 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:
   • completionReference — the transaction identifier from the original open pre-auth response; make sure the data type is String.
   • amount — the amount is mandatory and the POS must declare it; 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.
2. The POS calls initiateIncrementPreAuth(requestParams, transactionCallbacks) 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.00 integrated increment pre-authorisation request.

var amt = '10000';
var ref = 12001

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

Handling the response

The response to the increment pre-auth request is returned to the POS by iClient using responseReceivedCallback at the completion of the increment pre-auth request. If the request is successful, the POS will be provided the result, the incremented amount, and the last 4 digits of the card PAN in the result, incrementalAmount, and panLastFourDigits fields — the POS must use them to display the result and the message for the user's reference, and adjust the open pre-auth amount with the increment.

Response example

{
  "result": "APPROVED",
  "incrementalAmount": "5000",
  "panLastFourDigits": "1234"
}

Closing a pre-auth

Making the request

The steps to be followed to initiate a complete 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 responseReceivedCallback and reference them in the function invocation correctly.

Example

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

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

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

Handling the response

The response to the complete pre-auth request is returned to the POS by iClient using responseReceivedCallback at the completion of the complete pre-auth request. If the request is successful, the POS will be provided the result and an additional message in the result and the message fields — the POS must use them to display the result and the message for the user's reference, and mark the pre-auth request as closed off.

Response example

{
  "result": "success",
  "message": "Complete preAuth request accepted"
}

Voiding a pre-auth

Making the request

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

1. The POS specifies the completion reference for the void request in the completionReference parameter 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 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);
}

Handling the response

The response to the void pre-auth request is returned to the POS by iClient using responseReceivedCallback at the completion of the void pre-auth request. If the request is successful, the POS will be provided the result and an additional message in the result and the message fields — the POS must use them to display the result and the message for the user's reference, and mark the pre-auth request as voided. If the request is unsuccessful, the POS must likewise use result and message to display the result and the error message for the user's reference.

Response example

{
  "result":"success",
  "message":"Void preAuth request accepted"
  }

Demo

JS Fiddle demo — open a pre-auth with a specified limit, then close it off with an amount you specify, or void it.