Skip to main content

Initiate Pre Authorisation

Overview and Usage​

The initial stage of the entire Pre Authorisation journey is to initiate a Pre Authorisation request, this will allow the merchant to reserve funds on a consumer’s card which can be Completed at a later point should the merchant wish to charge the consumer, the merchant can also choose to Top-Up the Pre Authorisation if required.

example

Scenario
A consumer books a stay at a hotel and pays for the room online prior to their arrival. On the day of arrival at the hotel the consumer visits the front desk to check-in and receive the room key etc. As part of this process the reception staff request a nominal pre-authorisation of the consumer’s card, the value of the pre-authorisation will vary depending on the hotel chain, location etc. but is likely to be between £50 to £100.

Solution
Initiate a pre-authorisation to provide the hotel with some coverage should the guest choose to use some of the facilities in the hotel such as room service or the mini bar. When a pre-authorisation is in place the consumer will likely see the held funds in their “Pending Transactions” section of their banking app and the amount will have been deducted from their “available balance” figure.

A Pre Authorisation requires a POST/transaction request to be sent to the axept® PRO solution, in the same way a SALE transaction is also initiated. Once axept® PRO has responded to the request it is recommended to start polling for transation updates via GET/transaction requests; this will not only keep the POS up-to-date with the transaction progress but also the final result including the preAuthId if successfully finalised.

The below diagram shows how a Pre Authorisation request works.

Top-Up with Payment Card

Pre Authorisation Request​

Start the Pre Authorisation process with sending a POST/transaction request with a transType set to PRE_AUTH. After a POST/transaction request axept® PRO should respond with a valid HTTPS Response Code, it may also contain data in the response body if expected.

Pre Authorisation with Payment Card​

POST Transaction Request
Query Parameters
tidEnumYour device serial number
Header Parameters
AuthorizationStringBearer 6945595921271780
Body Parameters
transTypeEnum"transType": "PRE_AUTH"
amountTransInteger"amountTrans":10000
referenceString"transaction_reference"
POST /POSitiveWebLink/1.2.0/rest/transaction?tid=1853195101

HTTP/1.1
Content-Type: application/json
disablePrinting: true
Authorization: Bearer 6945595921271780
User-Agent: PostmanRuntime/7.26.8
Accept: */*
Host: 192.168.0.75:8080
Accept-Encoding: gzip, deflate, br
Connection: keep-alive
Content-Length: 127

{
    "transType": "PRE_AUTH",
    "amountTrans": 10000,
    "reference": "transaction_reference"
}
POST Transaction Response

Please select one of the below HTTPS Response Codes:

HTTP Response CodeDescription
201"Transaction Created"
This indicates that axept® PRO has received the request and the Pre Auth transaction has started on the payment device.
HTTP/1.1 201 Transaction Created
Content-Type: application/json
Date: Wed, 3 Sep 2025 14:44:25 GMT
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: POST, GET, OPTIONS, DELETE
Access-Control-Max-Age: 86400
Access-Control-Allow-Headers: *
Allow: POST, GET, OPTIONS, DELETE
Connection: keep-alive
Content-Encoding: gzip
Transfer-Encoding: chunked

{
   "amountCashback":0,
   "amountGratuity":0,
   "amountTrans":10000,
   "transType":"PRE_AUTH",
   "uti":"32179A36-DD12-4235-9DA7-C09EA12111FF"
}

Pre Authorisation with Card Acquisition​

If you are using the full Card Acquisition flow then you will need to send a Pre Authorisation request containing the uti and cardToken obtained in the Card Acquisition step. These will need to be included in the POST/transaction request body of your Pre Authorisation transaction.

IMPORTANT NOTE

If you are using the Simplified Flow then this means of initiating a Pre Authorisation will not be available to you.

POST Transaction Request
Query Parameters
tidEnumYour device serial number
Header Parameters
AuthorizationStringBearer 6945595921271780
Body Parameters
transTypeEnum"transType": "PRE_AUTH"
amountTransInteger"amountTrans":10000
cardTokenIntegerThe offline cardtoken from the Card Acquisition stage.
utiIntegerThe uti from the Card Acquisition stage.
referenceString"transaction_reference"
POST /POSitiveWebLink/1.2.0/rest/transaction?tid=1853195101

HTTP/1.1
Content-Type: application/json
disablePrinting: true
Authorization: Bearer 6945595921271780
User-Agent: PostmanRuntime/7.26.8
Accept: */*
Host: 192.168.0.75:8080
Accept-Encoding: gzip, deflate, br
Connection: keep-alive
Content-Length: 127

{
    "transType": "PRE_AUTH",
    "amountTrans": 10000,
    "cardToken": "tVobJ/OglLJN75q11iFKavlRxSItypd1vXbwh41v80wfMQ==",
    "uti":419C6D76-EB3A-447B-9E22-5940F4B2B974,
    "reference": "transaction_reference"
}
POST Transaction Response

Please select one of the below HTTPS Response Codes:

HTTP Response CodeDescription
201"Transaction Created"
This indicates that axept® PRO has received the request and the Pre Auth transaction has started on the payment device.
HTTP/1.1 201 Transaction Created
Content-Type: application/json
Date: Wed, 3 Sep 2025 14:44:25 GMT
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: POST, GET, OPTIONS, DELETE
Access-Control-Max-Age: 86400
Access-Control-Allow-Headers: *
Allow: POST, GET, OPTIONS, DELETE
Connection: keep-alive
Content-Encoding: gzip
Transfer-Encoding: chunked

{
   "amountCashback":0,
   "amountGratuity":0,
   "amountTrans":10000,
   "transType":"PRE_AUTH",
   "uti":"419C6D76-EB3A-447B-9E22-5940F4B2B974"
}

Cancel Pre Authorisation Request​

You can cancel a Pre Authorisation request at any time up to and including the Present Card screen, once a card has been presented it is not possible to cancel the transaction other than on the PED itself if the option is still available.

DELETE Transaction Request
Query Parameters
tidEnumYour device serial number
Header Parameters
AuthorizationStringBearer 6945595921271780
DELETE /POSitiveWebLink/1.1.0/rest/transaction?tid=1853195101

HTTP/1.1
Content-Type: application/json
Authorization: Bearer 6945595921271780
User-Agent: PostmanRuntime/7.45.0
Accept: */*
Postman-Token: 2760fa41-3e4c-410c-9ca6-64e9ba7f5b2a
Host: 192.168.0.201:8080
Accept-Encoding: gzip, deflate, br
Connection: keep-alive
DELETE Transaction Response

Please select one of the below HTTPS Response Codes:

HTTP Response CodeDescription
200This indicates that axept® PRO has received the request and the Pre Authorisation transaction has has been cancelled on the payment device.
HTTP/1.1 200 Response Not set
Content-Type: application/json
Date: Mon, 8 Sep 2025 13:23:35 GMT
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: POST, GET, OPTIONS, DELETE
Access-Control-Max-Age: 86400
Access-Control-Allow-Headers: *
Allow: POST, GET, OPTIONS, DELETE
Connection: keep-alive
Content-Encoding: gzip
Transfer-Encoding: chunked

{
   "amountCashback":0,
   "amountDiscount":0,
   "amountGratuity":0,
   "amountTrans":10000,
   "cardCaptureMethod":"NOT_CAPTURED",
   "cardPan":"****************",
   "cardPanSequenceNumber":"-01",
   "cardScheme":"DEFAULT",
   "cardSchemeId":0,
   "cardType":"NONE",
   "cvmPinVerified":false,
   "cvmSigRequired":false,
   "cvmType":"NO_CVM_SET",
   "dccResults":{
      "dccStatus":"NotAttempted"
   },
   "errorText":"",
   "isDeferred":false,
   "merchantId":"82603400147",
   "merchantLocation":[
      "Address Line 1"
   ],
   "merchantName":"axept® PRO",
   "merchantReference":"E26CD070652A",
   "penniesAmount":0,
   "receiptNumber":34,
   "retrievalReferenceNumber":"000034490001",
   "softwareVersion":"1.00.58-12189",
   "stan":"0",
   "terminalId":"03400149",
   "transApproved":false,
   "transCancelled":true,
   "transCurrencyCode":"GBP",
   "transCurrencyNum":"826",
   "transDateTime":"2025-09-08 14:23:10",
   "transDateTimeEpoch":1757337790888,
   "transPartiallyApproved":false,
   "transType":"PRE_AUTH",
   "uti":"6BA29E69-09BB-4089-BAD8-E7E515DF7C48",
   "DisplayData":[
      {
         "value":1,
         "description":"Transaction started"
      },
      {
         "value":13,
         "description":"GetCard Screen Displayed"
      },
      {
         "value":10,
         "description":"Transaction Cancelled"
      },
      {
         "value":97,
         "description":"Remote Cancelled"
      },
      {
         "value":10,
         "description":"Transaction Cancelled"
      },
      {
         "value":12,
         "description":"Transaction Finished"
      }
   ]
}

Pre Authorisation Polling​

Once a Pre Authorisation request has been successful and the transaction commences on axept® PRO, you can start polling the transaction status and progress using GET/transaction requests with the uti from the POST/transaction response (or from the request if you specified the uti in the original request).

When a GET /transaction request is executed, you should receive a response from axept® PRO with a valid HTTPS response code and message. Upon transaction completion a GET/transaction response should return a 200 HTTPS response code with all the transaction data.

GET Transaction Request
Query Parameters
tidEnumYour device serial number
utiEnumThe uti from the current Pre Authorisation transaction in progress/completed.
Header Parameters
AuthorizationStringBearer 6945595921271780
GET /POSitiveWebLink/1.1.0/rest/transaction?tid=1853195101&uti=B6A54EA1-967E-403D-A432-8015C7554751

HTTP/1.1
Content-Type: application/json
Authorization: Bearer 6945595921271780
User-Agent: PostmanRuntime/7.45.0
Accept: */*
Postman-Token: 927bdc55-8790-4daf-ad89-0ef3794daf7e
Host: 192.168.0.201:8080
Accept-Encoding: gzip, deflate, br
Connection: keep-alive
GET Transaction Response
Please select one of the below HTTPS response codes:
HTTP response codeDescription
206"Transaction in progress"
This indicates that axept® PRO has received the request and the Pre Auth transaction has started on the payment device.
HTTP/1.1 206 Transaction in progress
Content-Type: application/json
Date: Fri, 5 Sep 2025 13:55:17 GMT
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: POST, GET, OPTIONS, DELETE
Access-Control-Max-Age: 86400
Access-Control-Allow-Headers: *
Allow: POST, GET, OPTIONS, DELETE
Connection: keep-alive
Content-Encoding: gzip
Transfer-Encoding: chunked

{
   "DisplayData":[
      {
         "value":1,
         "description":"Transaction started"
      },
      {
         "value":13,
         "description":"GetCard Screen Displayed"
      }
   ]
}

best practice

A successful Pre Authorisation will return a preAuthId in a GET/transaction response, you will need this to utilise the Top-Up, Completion and Reversal actions without the physical card being present, it is also used to keep track of all Pre Auths that are currently active.