Skip to main content

Top-Up Pre Authorisation

Overview and Usage​

It may become necessary to add additional costs/charges to an active Pre Authorisation, for example, in a hotel a customer may want to use an additional service that was not part of the original booking. In these scenarios you can use the Top-Up feature to add to the original Pre Authorised amount.

example

Scenario
A consumer has booked a stay in a hotel for three days on business. They have already checked in and been through the initial processes including the processing of a pre-authorisation on their card for £100.

Due to issues experienced on the business trip the consumer needs to stay for a full week instead of the original three days. The consumer visits reception and successfully extends the room booking for that time and as a result the £100 currently pre-authorised is unlikely to cover the food and bar bills for this additional time.

Solution
The receptionist informs the consumer that they need to increase the pre-authorisation to cover the potential spend, this is a Top Up or incremental authorisation.

Carrying out a Top-Up works in the same way as a Pre Authorisation that we have already covered, however you can choose to carry it out either by:

  • Using the original payment card used on the original Pre Authorisation, this requires the cardholder to be present.
  • Using the preAuthId from the original Pre Authorisation, this does not require the cardholder to be present.

The below images show the Top-Up flow for both approaches:

Top-Up with Pre Auth ID

Top-up Request​

To initiate a Top-Up you need to send a POST/transaction request with the transType set to TOP_UP, if you want to run a Top-Up without the card then make sure to include the preAuthId from the initial Pre Authorisation response. See the below examples of how to carry out the POST/transaction request:

Top-up with Payment Card​

POST Transaction Request
Query Parameters
tidEnumYour device serial number
Header Parameters
AuthorizationStringBearer 6945595921271780
Body Parameters
transTypeEnum"transType": "TOP_UP"
amountTransInteger"amountTrans":5000
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.45.0
Accept: */*
Postman-Token: 70fca896-6690-45aa-bbfd-f9c14f34d79f
Host: 192.168.0.201:8080
Accept-Encoding: gzip, deflate, br
Connection: keep-alive
Content-Length: 56
 
{
    "amountTrans": 5000,
    "transType": "TOP_UP"
}
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 Top-Up 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": 5000,
    "transType": "TOP_UP",
    "uti": "3986B1FC-AA6F-458F-9187-B66858481F99"
}

Top-up with preAuthId​

POST Transaction Request
Query Parameters
tidEnumYour device serial number
Header Parameters
AuthorizationStringBearer 6945595921271780
Body Parameters
transTypeEnum"transType": "TOP_UP"
amountTransInteger"amountTrans":5000
preAuthIdStringpreAuthId from the original Pre Authorisation request.
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.45.0
Accept: */*
Postman-Token: d0722f56-0bcd-4a22-be63-be6a491306ff
Host: 192.168.0.201:8080
Accept-Encoding: gzip, deflate, br
Connection: keep-alive
Content-Length: 93
 
{
    "amountTrans": 5000,
    "transType": "TOP_UP",
    "preAuthId": "09051442084639"
}
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 Top-Up 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": 5000,
    "transType": "TOP_UP",
    "uti": "3986B1FC-AA6F-458F-9187-B66858481F99"
}

Cancel Top-Up Request​

You can cancel a Top-Up 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.

IMPORTANT NOTE

When using the preAuthId approach you will not be able to submit a DELETE/transaction request as axept® PRO will immediately move to the Card Processing screen, leaving no time to cancel the request. Ensure that any POST/transaction request being sent using the preAuthId is correct to avoid issue, however in the event of a mistake you can utilise further Top-Up requests and Reversals using partial amounts to correct the authorisedBalance.

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 Top-Up 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":5000,
   "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":"",
   "penniesAmount":0,
   "receiptNumber":47,
   "retrievalReferenceNumber":"000047490001",
   "softwareVersion":"1.00.58-12189",
   "stan":"0",
   "terminalId":"03400149",
   "transApproved":false,
   "transCancelled":true,
   "transCurrencyCode":"GBP",
   "transCurrencyNum":"826",
   "transDateTime":"2025-09-08 14:30:14",
   "transDateTimeEpoch":1757338214563,
   "transPartiallyApproved":false,
   "transType":"TOP_UP",
   "uti":"95A97BBC-A9FB-4573-BF1C-789E8626FFDD",
   "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"
      }
   ]
}

Top-up Polling​

Once a Top_up 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.

The below shows examples of such responses plus other possible HTTPS response codes you may receive.

GET Transaction Request
Query Parameters
tidEnumYour device serial number
utiEnumThe uti from the current Top-Up transaction in progress/completed.
Header Parameters
AuthorizationStringBearer 6945595921271780
GET /POSitiveWebLink/1.1.0/rest/transaction?tid=1853195101&uti=D4ED4B02-1EFC-4BDA-A3E4-C226B93F44FE

HTTP/1.1
Content-Type: application/json
Authorization: Bearer 6945595921271780
User-Agent: PostmanRuntime/7.45.0
Accept: */*
Postman-Token: 7e302159-0499-4a38-b9bf-f20a21511956
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"
The body of the response will include the list of status objects to indicate how far the transaction has progressed.
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"
      }
   ]
}