Transaction Request

Overview and Usage

If you are using the Simplified Flow then this is your first step. You may however have already completed Card Acquisition and want to either start a transaction, or cancel the Card Acquisition.

This section will show you how to initiate a transaction using the /transaction URI, how to poll for the status of the transaction, and then if required, how to cancel the transaction and return axept® PRO to an idle state.

Transaction Request


POST /transaction

URL

https://(TerminalIP):8080/POSitiveWebLink/1.1.0/rest/transaction

An HTTPS POST request should be sent to the above URL with the following parameters:

POST /transaction - Query String Parameters
Field NameStateData TypeDescription
tidMandatoryString

This is the serial number of the PAX IM30 that should process the transaction.

disablePrintingOptionalString

This will prevent the terminal from printing the EFT receipts. This will be useful to POS systems that wish to generate their own receipts.

When the device that axept® PRO is running on does not have an integrated printer, such as the PAX IM30, axept® PRO will display the merchant and cardholder receipts on screen. It is also possible to configure the device to email the receipts to the merchant and the cardholder.
This flag, when set to true, will also disable this view/email functionality.

Further information is available in the Receipts section

POST /transaction - Header Parameters
AuthorizationMandatoryStringThis field should be populated with a value of
Bearer 6945595921271780
POST /transaction - Body Parameters
transactionRequestMandatoryObjectProvides the required information to initiate a card acquisition sessionth axept® PRO.

POST /transactionRequest Parameters

POST /transaction - /transactionRequest Parameters
transTypeMandatoryEnum

Indicates how the transaction should be processed. The following values are allowed:

SALEThis value will result in funds being authorised/debited from the cardholder's account.
REFUNDThis will result in funds being credited to the cardholder's account.
AUTHORISATION_ONLYThis will instruct axept® PRO to seek an authorisation for the specified amount(s) on the presented card.

If the authorisation is successful, axept® PRO will do nothing further with the funds. The funds will be ring fenced on the cardholder's account and impact their Available to Spend balance.
REVERSALOnly to be used against a previous AUTHORISATION_ONLY transaction.

Should the POS decide that there is no need to take the authorised funds from the cardholder's account, a REVERSAL should be requested so that the cardholder's account does not have their Available to Spend impacted.
SETTLEMENT_ONLYOnly to be used against a previous AUTHORISATION_ONLY transaction.

Should the POS decide that there is a need to take the authorised funds from the cardholder's account, the settlement only will initiate the transfer of the authorised funds for the specified amountTrans.

If the POS has processed an AUTHORISATION_ONLY and does not wish to take the authorised amount from a cardholders account, a SETTLEMENT_ONLY with amounTrans set to 0 can be requested to reverse the authorised amount.
amountTransConditionalInteger

Amount of the transaction in minor units not including cashback/tips etc. For example, £10.00 would be represented as 1000.

This is a mandatory field for SALE, REFUND, AUTHORISATION_ONLY and SETTLEMENT_ONLY transactions. This field should be omitted for reversals.

amountGratuityConditionalInteger

Amount of the gratuity in minor units. For example, £5.00 would be represented as 500.

This is an optional field for SALE, AUTHORISATION_ONLY and SETTLEMENT_ONLY transactions. This field should be omitted for refunds and reversals.

amountCashbackConditionalInteger

Amount of the Cashback in minor units. For example, £15.00 would be represented as 1500.

This is an optional field for SALE, AUTHORISATION_ONLY and SETTLEMENT_ONLY transactions. This field should be omitted for refunds and reversals.

referenceOptionalStringReference assigned to the transaction by the merchant’s system.

This field is restricted to a maximum of 50 characters and only supports A to Z, a to z, 0 to 9 and _ (an underscore).
utiConditionalString

This field is Mandatory if transType is REVERSAL or SETTLEMENT_ONLY. Additionally it must be provided if the transType is AUTHORISATION_ONLY in instances where the transaction was initiated using the /cardAcquisition resource.

In scenarios where the transType is REVERSAL or SETTLEMENT_ONLY, the value in this field will be the uti returned on the POST to /transaction for the preceding AUTHORISATION_ONLY.

For transactions initiated via a POST to /cardAcquisition, the value in this field will reflect the uti received in response from a POST on /cardAcquisition.

axept® PRO will only cache card details captured during the last card acquisition session and only until either a DELETE or POST to /transaction is received by axept® PRO. As such, only the most recent uti from a POST to /cardAcquisition will be supported.

POST Example Request

Postman Request
POST https://192.168.10.44:8080/POSitiveWebLink/1.1.0/rest/transaction?tid=1640005298&disablePrinting=true
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": "SALE",
"amountTrans": 100,
"reference": "TEST_CARD"
}

POST Response Fields

axept® PRO will return one of five response codes:

HTTP Response CodeDescription
200Reversal initiated.
This indicates that axept® PRO is reversing a previously authorised transaction. It is only seen if the POST has transType of SETTLEMENT_ONLY and amountTrans = 0.
201Transaction created.
206Transaction in progress – a new transaction cannot be started until the current one completes.
400Bad input parameter.
Details would be returned in a text description
403Not Authorised
408Request timeout.

POST Example Responses

HTTP/1.1 201 Transaction Created
Content-Type: application/json
Date: Wed, 20 Jan 2021 12:18:31 GMT
Allow: POST, GET, OPTIONS, DELETE
Access-Control-Max-Age: 86400
Access-Control-Allow-Methods: POST, GET, OPTIONS, DELETE
Access-Control-Allow-Headers: *
Access-Control-Allow-Origin: *
Connection: keep-alive
Content-Encoding: gzip
Transfer-Encoding: chunked
{
"amountTrans": 100,
"transType": "SALE",
"uti": "3986B1FC-AA6F-458F-9187-B66858481F99"
}
note

If the HTTP response code is 201 or 200, the body of the response will include the Unique Transaction Identifier (UTI) assigned by axept® PRO.

You can now use GET /transaction to poll the status of axept® PRO while the transaction is processed.


GET /transaction

URL

https://(TerminalIP):8080/POSitiveWebLink/1.1.0/rest/transaction

An HTTPS GET request should be sent to the above URL with the following parameters:

GET /transaction - Query String Parameters
Field NameStateData TypeDescription
tidMandatoryString

This is the serial number of the PAX IM30 that should process the transaction.

utiOptionalStringThis is the Unique Transaction Identifier that axept® PRO provided in the body of a response to a POST on the /transaction resource.
POST /transaction - Header Parameters
AuthorizationMandatoryStringThis field should be populated with a value of
Bearer 6945595921271780
caution

axept® PRO will cache the days transactions until either a Z report is processed, or a reboot occurs

As such, you are able to query more than the last transaction. You should however query the transaction as soon as possible and not rely on axept® PRO to provide data on historic transactions.

GET Example Request

Postman Request
GET https://192.168.10.44:8080/POSitiveWebLink/1.1.0/rest/transaction?tid=1640005298&uti=784F7278-7326-4935-B4F2-B46B5E3BBAC5
HTTP/1.1
Content-Type: application/json
Authorization: Bearer 6945595921271780
User-Agent: PostmanRuntime/7.26.8
Accept: */*
Host: 192.168.0.75:8080
Accept-Encoding: gzip, deflate, br
Connection: keep-alive

GET Response Fields

In response to this, axept® PRO will return one of six response codes:

HTTP Response CodeDescription
200axept® PRO can find a completed transaction that matches the provided criteria. The body of the response will provide the transaction data.
206Transaction in progress.
The body of the response will include the list of status objects to indicate how far the transaction has progressed.
400Bad input parameter.
Details would be returned in a text description
403Not Authorised
404Transaction response not found or not available.
This indicates that the provided uti value is not found by axept® PRO.
408Request timeout

You can use the HTTP response code 206 response code to determine that axept® PRO is still busy with the transaction. Once the transaction has finished, axept® PRO will return HTTP response code 200 and the following fields may be returned:

GET Response 200 Fields

note

Not all these fields will be provided in every transaction. For example, if the cardType is MSR (Magnetic Stripe Read) then all fields related to EMV processing will not be provided.

GET /transaction Response Body Parameters
Field NameData TypeDescription
transTypeEnumProvides the transaction type that was performed:
SALEThis value will result in funds being authorised & debited from the cardholder’s account.
REFUNDThis will result in funds being credited to the cardholders account from the merchant’s account.
AUTHORISATION_ONLYThis will instruct axept® PRO to seek an authorisation for the specified amount(s) on the presented card. If the authorisation is successful, axept® PRO will do nothing further with the funds. The funds will be ring fenced on the consumers account and impact their Available to Spend balance.
REVERSALOnly to be used against a previous AUTHORISATION_ONLY transaction. Should the POS decide that there is no need to take the authorised funds from the consumers account, a reversal should be requested so that the consumer’s account does not have their Available to Spend impacted.
SETTLEMENT_ONLYOnly to be used against a previous AUTHORISATION_ONLY transaction. Should the POS decide that there is a need to take the authorised funds from the consumer’s account, the settlement only will initiate the transfer of the authorised funds.
transApprovedBooleanIndicates if the transaction was approved.
transPartiallyApprovedBooleanIn instances where the EPOS performs an AUTHORISTION_ONLY followed later by a SETTLEMENT_ONLY, there is the possibility for the settlement amount to be greater than the authorised amount. In these instances, axept® PRO will seek a further authorisation with the acquirer as part of processing the SETTLEMENT_ONLY. Should this incremental authorisation fail, axept® PRO will settle for the previously authorised amount (the amountTrans requested in the AUTHORISATION_ONLY). In this particular scenario, axept® PRO will return transPartiallyApproved set to True so that the integrated EPOS knows that this occurred. Additionally, the amountTrans in response to GET /transaction will reflect the amount this is to be settled to the acquirer.
transCancelledBooleanIndicates if the transaction was cancelled.
utiStringUnique Transaction Identifier as generated by axept® PRO.
amountTransIntegerAmount of the transaction in minor units not including cashback/tips etc. For example, £10.00 would be represented as 1000.
amountGratuityIntegerAmount of the gratuity in minor units. For example, £5.00 would be represented as 500.
amountCashbackIntegerAmount of the cashback in minor units. For example, £15.00 would be represented as 1500.
amountDiscountIntegerNot relevant to axept® PRO processing unattended transactions.
cvmSigRequiredBooleanSignifies whether the transaction required the cardholder to perform signature verification.
cvmPinVerifiedBooleanSignifies whether the transaction required the cardholder to complete PIN verification.
transCurrencyCodeStringProvides a 3-character currency code for the transaction. The values provided comply with ISO4217 alphabetic code i.e. GBP, EUR etc.
terminalIdStringReflects the terminal identifier used when processing the transaction. NB: This does differ to tid – the tid reflects the hardware identifier whereas the terminalId reflects a ‘soft’ identifier for the payment channel.
merchantIdStringReflects the merchant identifier used when processing the transaction.
softwareVersionStringProvides the software version of axept® PRO.
receiptNumberIntegerThe receipt number for this transaction.
retrievalReferenceNumberStringThe retrieval reference number for this transaction.
paymentIdStringThis is an identifier for the transaction from Optomany’s central host (the axept® Platform).
responseCodeStringThe 2-digit response code from the acquirer. Common response codes are:
00Approval
02Referral
(which axept® PRO Unattended will treat as a denial)
03Denial
05Denial
21Denial
30Denial
55Denial
63Denial
85Approval
96Denial
98Denial
99Denial
Y1Transaction does not need to go online – offline approved
Z1Transaction does not need to go online – offline denial
Y3Unable to go online – offline approved
Z3Unable to go online – offline denial
stanStringSystem Trace Audit Number.
authorisationCodeStringThe authorisation code returned from the acquirer (e.g. 123ABC).
merchantTokenIdStringThe Optomany token for the card used to complete the transaction.
cardPanStringThe masked PAN (Primary Account Number) of the card. The string length reflects the length of the PAN but only the last 4 digits will be provided, the preceding digits are obfuscated with asterisks e.g. ************5454.
cardExpiryDateStringThe expiry date of the card used for the transaction. Format is YYMM e.g. a card expiring in April 2022 will be expressed as 2204.
cardStartDateStringThe start date of the card used (if available).  Format is YYMM e.g. a card issued in November 2019 will be expressed as 1911.
cardSchemeStringThe name of the scheme used (e.g. Visa\Mastercard).
cardPanSequenceNumberStringThe PAN sequence number if available.
cardTypeStringThe capture methods of the card. Possible values are:
EMVThe card was inserted and a chip was read.
MSRThe card was swiped and details captured via a magnetic stripe read.
CTLSThe card details were presented using contactless technology.
ManualThe card number was manually keyed in. Please note that this disabled when operating in Unattended environments but has been documented for completeness.
emvAidStringIf the card was captured via EMV or Contactless, this field will provide the application identifier of the presented card.
emvTsiStringIf the card was captured via EMV or Contactless, this field will provide the EMV standards Transaction Status Information (e.g. E800)
emvTvrStringIf the card was captured via EMV or Contactless, this field will provide the EMV standards Transaction Verification Results (e.g. 0080000000)
emvCardholderNameStringIf the card was captured via EMV or Contactless, this field will provide the cardholder name if it has been obtained during EMV processing.
emvCryptogramStringAs part of EMV processing, a cryptogram will be generated for the transaction.
emvCryptogramTypeStringThis provides the cryptogram type used during EMV processing for the transaction.
Statuses2Array of ObjectsAn array of statuses for the transaction to show all stages during processing the transaction.
errorCodeStringReserved for future use
errorTextString Reserved for future use
merchantReferenceStringThis echo’s back the reference supplied by the integrated client when the transaction was initiated
merchantLocationArray of StringsThis provides address line 1 and 2 of the merchant store as set up on Optomany’s systems
merchantNameStringThis reflects the merchant store name as set up on Optomany’s systems
transDateTimeStringaxept® PRO’s date/time stamp for the transaction. Formatted as YYYY-MM-DD HH:MM:SS
DisplayDataArray of ObjectsProvides a list of statuses that axept® PRO progressed through when processing the transaction

GET Example Responses

HTTP/1.1 200
Content-Type: application/json
Date: Wed, 20 Jan 2021 16:05:33 GMT
Allow: POST, GET, OPTIONS, DELETE
Access-Control-Max-Age: 86400
Access-Control-Allow-Methods: POST, GET, OPTIONS, DELETE
Access-Control-Allow-Headers: *
Access-Control-Allow-Origin: *
Connection: keep-alive
Content-Encoding: gzip
Transfer-Encoding: chunked
{
"amountCashback": 0,
"amountDiscount": 0,
"amountGratuity": 0,
"amountTrans": 100,
"authorisationCode": "123ABC",
"cardExpiryDate": "2512",
"cardPan": "************0102",
"cardPanSequenceNumber": "001",
"cardScheme": "Mastercard",
"cardStartDate": "040101",
"cardType": "EMV",
"cvmPinVerified": true,
"cvmSigRequired": false,
"emvAid": "A0000000041010",
"emvCryptogramType": "TC",
"emvTsi": "E800",
"emvTvr": "0000008000",
"errorCode": "",
"errorText": "",
"merchantId": "520334508311111",
"merchantLocation": [
"6 Cedarwood",
"Crockford Lane"
],
"merchantName": "Charger Location 1",
"merchantReference": "TEST_REF5",
"merchantTokenId": "WwcD4zbBoseyZD4dcSjIzjNSkif2kb0c0GIKuKLY3KcfMQ==",
"paymentId": "34970/18/09022021155300152",
"receiptNumber": 41,
"responseCode": "00",
"retrievalReferenceNumber": "000041970001",
"softwareVersion": "2.00.00.5038",
"stan": "18",
"terminalId": "1640005297",
"transApproved": true,
"transCancelled": false,
"transCurrencyCode": "GBP",
"transDateTime": "2021-02-09 15:52:41",
"transType": "SALE",
"emvCryptogram": "A4E0C33B3922B996",
"uti": "BE00D527-406B-4A19-BD60-DCE8B15330DB",
"DisplayData": [
{
"value": 1,
"description": "Transaction started"
},
{
"value": 13,
"description": "GetCard Screen Displayed"
},
{
"value": 6,
"description": "Card type EMV"
},
{
"value": 15,
"description": "Pin Requested(Offline)"
},
{
"value": 17,
"description": "Host Approved"
},
{
"value": 2,
"description": "Transaction Approved"
},
{
"value": 12,
"description": "Transaction Finished"
}
]
}

Transaction Complete

Transaction Complete

At this point, the /transaction is considered complete.


DELETE /transaction

There are three main use cases for using the DELETE request.

  1. Aborting a /cardAcquisition request after the card has been Acquired.
  2. Aborting a /transaction request during the payment process.
  3. Cancelling a /transaction or /cardAcquisition request which is in flight but the uti is not known.
URL

https://(TerminalIP):8080/POSitiveWebLink/1.1.0/rest/transaction

An HTTPS DELETE request should be sent to the above URL with the following parameters:

DELETE /transaction - Query String Parameters
Field NameStateData TypeDescription
tidMandatoryString

This is the serial number of the PAX IM30 that should process the transaction.

DELETE /transaction - Header Parameters
AuthorizationMandatoryStringThis field should be populated with a value of
Bearer 6945595921271780

DELETE Example Request

Postman Request
DELETE https://192.168.10.44:8080/POSitiveWebLink/1.1.0/rest/transaction?tid=1640005297
HTTP/1.1
Content-Type: application/json
Authorization: Bearer 6945595921271780
User-Agent: PostmanRuntime/7.26.8
Accept: */*
Host: 192.168.0.75:8080
Accept-Encoding: gzip, deflate, br
Connection: keep-alive
caution

The DELETE request can be sent at any point after axept® PRO responds to the POST on /transaction or /cardAcquisition with response code 206.

Transactions using the Simple Flow can only be cancelled up to and including the point where axept® PRO is waiting for a card (a “status Value” of 13 and status Description of "GetCard Screen Displayed"). Once the transaction moves beyond that stage, an integrated cancel is not possible. You should continue to poll the GET for a ResponseCode 200.

More detail on status Values can be found in the DisplayData section

DELETE Response

The below HTTP response status codes may be returned in response to the DELETE:

HTTP Response CodeDescription
200Request successfully posted and transactions has been cancelled
400Bad input parameter.
Details would be returned in a text description
403Not Authorised

DELETE Example Response

Cancelled after /transaction request, before/during Status 13
HTTP/1.1 200
Content-Type: application/json
Date: Wed, 20 Jan 2021 13:36:22 GMT
Allow: POST, GET, OPTIONS, DELETE
Access-Control-Max-Age: 86400
Access-Control-Allow-Methods: POST, GET, OPTIONS, DELETE
Access-Control-Allow-Headers: *
Access-Control-Allow-Origin: *
Connection: keep-alive
Content-Encoding: gzip
Transfer-Encoding: chunked
{
"amountCashback": 0,
"amountDiscount": 0,
"amountGratuity": 0,
"amountTrans": 100,
"cardPan": "****************",
"cardPanSequenceNumber": "-01",
"cardScheme": "",
"cardType": "NONE",
"cvmPinVerified": false,
"cvmSigRequired": false,
"errorCode": "",
"errorText": "",
"merchantId": "520334508311111",
"merchantReference": "TEST_CARD",
"receiptNumber": -1,
"softwareVersion": "1.00.27.4987",
"stan": "0",
"terminalId": "1640005297",
"transApproved": false,
"transCancelled": true,
"transCurrencyCode": "GBP",
"transType": "SALE",
"uti": "65B10A83-1E5F-422F-B7ED-27B6CF7AB055",
"DisplayData":"[
{
"value": 1,
"description": "Transaction started"
},
{
"value": 13,
"description": "GetCard Screen Displayed"
},
{
"value": 10,
"description": "Transaction Cancelled"
}
]
}