Skip to main content

Complete Pre Authorisation

Overview and Usage​

When a Pre Authorisation is ready to be finalised, for example in a hotel scenario when a customer is checking out, the POS system can send a Completion request to axept® PRO, either with or without the preAuthId, which will then trigger the completion process. A Completion step can be looked at as a final committal for the transfer of funds, with the final amount being confirmed as well.

example

Scenario
A consumer has stayed in a hotel for a week and during check-in a pre-authorisation was carried out for exactly the value of two set meals that he planned to have at the hotel. The consumer checks out from the hotel on his last morning and requests the bill. He agrees that the charges match what he was expecting and is happy to have his pre-authorised card charged for the full pre-authorisation.

Solution
The receptionist accesses the hotels EPOS solution and initiates the completion of the transaction which completes successfully. The card is charged, and the consumer leaves the hotel with a copy of the bill containing the transaction details.

Similar to a Top-Up request, you make a POST/transaction request with a new transType of COMPLETION and can choose to:

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

The below images show the Completion flow for both approaches:

Completion with Pre Auth ID

Completion with authorisedBalance​

The most common scenario when running a Completion of a Pre Authorisation is the settle the full amount that has been authorised, this includes any subsequent Top-Ups. The running total for a Pre Authorisation is called the authorisedBalance and can be checked any time via GET requests.

further reading

Obtaining the current authorisedBalance of a Pre Authorisation is covered in the Manage Pre Authorisations section.

Using Payment Card​

POST Transaction Request
Query Parameters
tidEnumYour device serial number
Header Parameters
AuthorizationStringBearer 6945595921271780
Body Parameters
transTypeEnum"transType": "COMPLETION"
amountTransInteger"amountTrans":15000
POST /POSitiveWebLink/1.1.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": 15000,
    "transType": "COMPLETION"
}
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 Completion 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": 15000,
    "transType": "COMPLETION",
    "uti": "3986B1FC-AA6F-458F-9187-B66858481F99"
}

Using preAuthId​

POST Transaction Request
Query Parameters
tidEnumYour device serial number
Header Parameters
AuthorizationStringBearer 6945595921271780
Body Parameters
transTypeEnum"transType": "COMPLETION"
amountTransInteger"amountTrans":15000
preAuthIdStringpreAuthId from the original Pre Authorisation request.
POST /POSitiveWebLink/1.1.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": 15000,
    "transType": "COMPLETION",
    "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 Completion 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": 15000,
    "transType": "COMPLETION",
    "uti": "3986B1FC-AA6F-458F-9187-B66858481F99"
}

Completion with Variable Amount​

The final amount you use in the Completion transaction does not need to be the same as the authorisedBalance, you can submit a value that is lower or higher than the authorisedBalance value if the circumstances call for it. The below scenario outlines a live example:

example
Scenario
A consumer has stayed in a hotel for one night, having booked and paid for the room online, and during check-in a pre-authorisation was carried out for the nominal amount of £100 as per the rules of the hotel chain. During his stay he ate dinner in the restaurant and had some drinks at the bar with friends, all of which were charged to his room. The next morning the consumer visits the reception desk to check out. The receptionist informs him that the final bill that needs to be settled is £120 and asks if he is happy to pay on the card that was pre-authorised. The consumer confirms that he is, and as a result the receptionist uses axept® PRO to perform the completion for £120 by entering the unique ID during the flow.
Solution
The consumer confirms that he is, and as a result the receptionist uses axept® PRO to perform the completion for £120 by entering the unique ID during the flow.
The consumer is charged £120 which is made up of two elements:

  • Original Pre-Authorisation = £100
  • Top-Up Authorisation = £20

The process of performing the incremental authorisation/top-up is managed by the Optomany Platform meaning that neither the operator nor consumer has to perform any additional tasks other than enter the final value.

Best Practice

Any required changes to the authorisedBalance amount should be handled as soon as they are required, this is to ensure that any additional amounts are secured for the merchant but also any deductions are also released back to the customer as soon as possible.

The below images show the Completion flow for both approaches, with card or preAuthId and whether you are using a greater or lower value in the transAmount:

Partial Completion with Pre Auth ID

The below examples have an authorisedBalance of £150.00 but a completion amount of £125.00 will be requested, however if you were to set a higher amount than the authorisedBalance such as £175.00, for example, this will also work.

Using Payment Card​

POST Transaction Request
Query Parameters
tidEnumYour device serial number
Header Parameters
AuthorizationStringBearer 6945595921271780
Body Parameters
transTypeEnum"transType": "COMPLETION"
amountTransInteger"amountTrans":12500
POST /POSitiveWebLink/1.1.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": 12500,
    "transType": "COMPLETION"
}
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 Completion 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": 12500,
    "transType": "COMPLETION",
    "uti": "3986B1FC-AA6F-458F-9187-B66858481F99"
}

Using preAuthId​

POST Transaction Request
Query Parameters
tidEnumYour device serial number
Header Parameters
AuthorizationStringBearer 6945595921271780
Body Parameters
transTypeEnum"transType": "COMPLETION"
amountTransInteger"amountTrans":12500
preAuthIdStringpreAuthId from the original Pre Authorisation request.
POST /POSitiveWebLink/1.1.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": 12500,
    "transType": "COMPLETION",
    "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 Completion 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": 12500,
    "transType": "COMPLETION",
    "uti": "3986B1FC-AA6F-458F-9187-B66858481F99"
}

Cancel Completion Request​

You can cancel a Completion 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 little to 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 Completion 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":1000,
   "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":49,
   "retrievalReferenceNumber":"000049490001",
   "softwareVersion":"1.00.58-12189",
   "stan":"0",
   "terminalId":"03400149",
   "transApproved":false,
   "transCancelled":true,
   "transCurrencyCode":"GBP",
   "transCurrencyNum":"826",
   "transDateTime":"2025-09-08 14:53:47",
   "transDateTimeEpoch":1757339627779,
   "transPartiallyApproved":false,
   "transType":"COMPLETION",
   "uti":"E36CF10C-4782-4F15-8469-1120F6C10251",
   "DisplayData":[
      {
         "value":1,
         "description":"Transaction started"
      },
      {
         "value":13,
         "description":"GetCard Screen Displayed"
      },
      {
         "value":97,
         "description":"Remote Cancelled"
      },
      {
         "value":10,
         "description":"Transaction Cancelled"
      },
      {
         "value":12,
         "description":"Transaction Finished"
      }
   ]
}

Completion Polling​

Once a Completion 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 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"
This indicates that axept® PRO has received the request and the Completion 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"
      }
   ]
}

IMPORTANT NOTE

Once a Completion is finalised the entire Pre Authorisation will have also been finalised and complete. Think of it as one complete transaction; the Completion phase is the last step in that long transaction flow so any additional Top Ups or partial Reversals will need to be handled as separate transactions.