Introduction
Overview and Usage
This section covers how to utilise axept® PRO Pre Authorisation transactions via the Weblink integration, this can be triggered either via one of the following flows:
If you have not yet familiarised yourself with the basic transactional flow of axept® PRO then please read this section first here, this section covers only the necessary parameters to trigger Pre Authorisations, Top Ups and Settlements and will not cover every parameter of a transaction request.
The below image shows a high-level overview of both approaches and how they work:
It can be stated that Card Acquisition relies on the Simplified Flow to accomplish a successful Pre Auth from start to finish, or Completion, and is more designed for an Unattended environment. Whereas the Simplified Flow is your industry standard Pre Authorisation flow normally utilised by Hospitaltiy for example.
In order to carry out an integration you will need to familiarise yourself with the following sections:
The Card Acquisition stage is optional and is not required to carry out a Pre Authorisation using the Simplified Flow, this stage is only required if you are wanting to utilise the Card Acquisition Pre Auth Flow, i.e. you are wanting to use Pre Authorisation in a Semi-attended or Unattended environment, or if wanting to accept MiFare Cards (see below).
We also recommend familiarising yourself with the Reverse Pre Authorisation and Manage Pre Authorisation sections as these will be useful in managing a currently live Pre Authorisation.
Parameters Overview
The Pre Authoriation flow works in the same way as a standard POST/transaction request and is compatible with a lot of the parameters that are related to this request. In the interest of expediency we will not cover the entirety of the parameters and instead we will focus on the parameters that are used with the Pre Authorisation feature.
You can find a complete list of all the transactional parameters in the Transaction Request section.
Key Header Parameters
| Parameter | Type | Requirement | Description |
|---|---|---|---|
| Authorzation | String | Mandatory | To be able to authorise a request to axept® PRO this field should be populated with a value of Bearer 6945595921271780 |
Key Query Parameters
| Parameter | Type | Requirement | Description |
|---|---|---|---|
| tid | String | Mandatory | The serial number of the axept® PRO device being targeted for the request. |
| uti | String | Conditional | Generated by the EPOS System at the start of either flow. When carrying out POST/transaction request (as part of the Card Acquisition flow), GET/cardAcquisition request or GET/transaction requests you will need to specify the uti that you are wanting to execute the request against. |
| silent | Boolean | Optional | Useful for Unattended environments. When enabled for the below transType's in a POST/transaction requests, axept® PRO will carry out the requests without prompting/displaying on the PED itself:
|
| reportType | String | Mandatory | Mandatory for a GET/reports request. For Pre Authorisations you will use the following reportType's:
|
| page | Integer | Conditional | Conditionally mandatory for a GET/reports request that has a reportType of ALL_OPEN_PA and must be used with the size parameter also. This parameter is used to specify the page number of the report to return of a currently live/active Pre Authorisation report. For example if there are 20 live Pre Authorisations on a PED and you specify a size of 10 and a page number of 2 it will return the 10 acive Pre Authorisations from the second page of the report. |
| size | Integer | Conditional | Conditionally mandatory for a GET/reports request that has a reportType of ALL_OPEN_PA and must be used with the page parameter also. This parameter is used to specify the maximum size (quantity of entries) of a currently live/active Pre Authorisation report will be returned from the page number specified. For example if there are 20 live Pre Authorisations on a PED and you specify a size of 10 and a page number of 2 it will return the 10 acive Pre Authorisations from the second page of the report. |
| preAuthId | String | Conditional | Obtained from a GET/transaction response body where the transType is set to PRE_AUTH and the HTTPS response code is 200. Conditionally mandatory only for when the original payment card for the Pre Authorisation is not available/being used for a GET/reports request with a reportType of STATUS_CHECK |
Key Request Body Parameters
| Parameter | Type | Requirement | Description |
|---|---|---|---|
| transType | Enum | Mandatory | Informs axept® PRO on the type of transaction being requested, for Pre Authorisation this would be:
|
| amountTrans | Integer | Conditional | Conditionally mandatory when used with a POST/cardAcquisition request or any of the following transType's in a POST/transaction request:
|
| reversalAmount | Enum | Conditional | Conditionally mandatory only when used in a POST/transaction requests when the transType is set to REVERSAL; use in place of the transAmount. |
| reference | String | Mandatory | Set by the EPOS System at the start of either flow. Reference assigned to the transaction by the merchant’s system, we recommend a combination of several fields, concatenated to ensure that the result is unique. Note: This field is restricted to a maximum of 50 characters and only supports upper and lower case alphanumerics and underscores ( _ ). You must not pass in any personally identfiable information in this field. See the Warning below for more information. |
| uti | String | Conditional | Generated by the EPOS System at the start of either flow. Conditionally mandatory when making a POST/transaction request with a transType of PRE_AUTH via the Card Acquisition flow. |
| preAuthId | String | Conditional | Obtained from a GET/transaction response body where the transType is set to PRE_AUTH and the HTTPS response code is 200. Conditionally mandatory only for when the original payment card for the Pre Authorisation is not available/being used for a POST/transaction requests containing the following transType's:
|