Skip to main content

GET transaction

GET Transaction is used to return a transaction and its status from axept® Connect Cloud. It can be used both for a single transaction, typically used in non-webhook flows, or for wider transaction searches and status updates and for limited reporting

GET /transaction Request​

URLs

TEST: https://optomany-axeptconnectcloudmerchant-ppe.azurewebsites.net/Transaction

LIVE: https://optomany-axeptconnectcloudmerchant-live.azurewebsites.net/Transaction

An HTTP GET should be sent to the above URLs with the below details:

POST /transaction - Header
Field NameStateData TypeDescription
AuthorizationMandatoryStringThis field should be populated with the bearer token returned in the Authentication step.

The format is ["Bearer "][Bearer Token] e.g.

Bearer eyJhbGciOiJIUzI1NiIsIn... (truncated)

Note the space between "Bearer" and the token.
POST /transaction - Parameters
utiMandatoryStringThe Unique transaction Id, provided by your EPOS solution when the transaction was started, and returned in the Payment Response.

Example GET /transaction Request​

GET https://optomany-axeptconnectcloudmerchant-ppe.azurewebsites.net/Transaction/604f2540-5af9-4f60-a889-449bd5dd17d5
Authorization: Bearer eyJhbGciOiJIUzI1NiIsIn.. [truncated]
User-Agent: PostmanRuntime/7.31.3
Accept: */*
Postman-Token: 0815a846-8c8a-44f4-87f8-e0795e57e435
Host: optomany-axeptconnectcloudmerchant-ppe.azurewebsites.net
Accept-Encoding: gzip, deflate, br
Connection: keep-alive

GET /transaction Response​

A successful response will return 200 OK and the following data fields. Transactions that are not at Complete status will not show all these fields.

caution

A transaction approval status must only be confirmed once status is at Complete.

GET /transaction Response
Field NameData TypeDescription
utiGUIDUnique client initiate GUID to represent the transaction.
transTypeStringIndicates how the transaction should be processed.
transApprovedBooleanIndicates whether the transaction was approved.
transApproved is the primary indicator of whether the transaction was successful.

It should be used by EPOS logic in conjunction with status = complete to determine the overall status of the transaction to the Consumer.
transPartiallyApprovedBooleanIndicates whether the transaction was partially approved.
transCancelledBooleanIndicates whether the transaction was cancelled.
amountTransIntegerAmount of the transaction in minor units not including cashback/tips etc.
amountGratuityIntegerAmount of the gratuity in minor units.
amountCashbackIntegerAmount of the Cashback in minor units.
cvmSignatureRequiredBooleanSignifies 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.
terminalIdStringReflects the terminal identifier (TID) used when processing the transaction
merchantIdStringReflects the merchant identifier (MID) used when processing the transaction.
softwareVersionStringProvides the software version of axept PRO.
receiptNumberStringThe receipt number for this transaction.
retrievalReferenceNumberStringThe retrieval reference number for this transaction.
paymentIdStringThis is an identifier for the transaction from DNA Payments’ central host.
responseCodeStringThe 2-character response code from the acquirer.
stanStringThe system trace audit number (EFT Sequence Number).
authorisationCodeStringThe authorisation code returned from the acquirer.
merchantTokenIdStringThe DNA Payments token for the card used to complete the transaction.
cardPanStringThe masked PAN (Primary Account Number) of the card.  This will be in ‘all starred bar the last four digits’ format.
cardExpiryDateStringThe expiry date of the card used for the transaction in ‘YYMM’ format.
cardStartDateStringThe start date of the card used for the transaction in ‘YYMM’ format (if available).
cardSchemeStringThe name of the card scheme used.
cardPanSequenceNumberStringThe PAN sequence number (if available).
cardTypeStringThe method used to obtain the card details.
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.
emvTvrStringIf the card was captured via EMV or Contactless, this field will provide the EMV standards Transaction Verification Results.
emvCardholderNameStringIf the card was captured via EMV or Contactless, this field will provide the cardholder name if it has been obtained during EMV processing.
emvCryptogramStringThe cryptogram generated as part of the EMV process.
emvCryptogramTypeStringThis provides the cryptogram type used during EMV processing for the transaction.
errorCodeStringThe error code associated with the error details.
errorTextStringThe error message associated with the error details.
referenceStringClient reference assigned to the transaction and echoed back in subsequent operations.
merchantLocationStringThis is the address (address line 1 and 2) of the merchant store as set up in the DNA Payments system.
merchantNameStringThis is the name of the merchant store as set up in the DNA Payments system.
transDateTimeDateTimeaxept PRO’s UTC date/time stamp for the transaction in ISO 8601-1:2019 format
createdDateTimeDateTimeUTC Date/Time the transaction was initiated by the merchant in ISO 8601-1:2019 format
merchantStoreIdIntegerDNA Payments issued identifier for the merchant’s store.
statusStringThe status of the transaction. This will be either:
OpenTransaction has been created but is not locked by a terminal as yet.
InProgressTransaction has been locked by a terminal and is being progressed on a terminal.
CompleteTransaction is completed.
posActionStatusIntegerAt transaction commencment this will always have a value of 0.
If used in conjunction with the posSignatureCheck value being set to true in the original transaction request; this value can update depending on whether a CVM Signature check is required for the transaction.
The possible values are:
0No signature required.
1Signature required.
2Signature accepted.
3Signature refused.
If you are wanting to utilise your EPOS printer to handle Signature Receipt printing, you need to ensure the EPOS is monitoring the posActionStatus value in GET/transaction response body data and to react/action accordingly if it changes.
posSignatureCheckBooleanIndicates if the retrieved transaction will rely on the EPOS system printer to print CVM Signature check receipts or if axept® PRO will handle the printing duties. If set to true then the EPOS system will handle the receipt printing and the posActionStatus will update accordingly based on signature requirements (see the previous table entry). If posSignatureCheck is omitted from the original transaction request the cloud will add this entry and default to false.
DisplayDataArray of ObjectsProvides a list of statuses that axept® PRO progressed through when processing the transaction. A complete list of the objects can be found under the Display Data section.
expirationDateStringThe expiration UTC date/time stamp for the retrieved transaction.
This is set during the initial transaction request and should be a minimum of 5 minutes from the createdDateTime to account potential delays in completion such as signature requests for example.
The date is in ISO 8601-1:2019 format
gratuityPromptIntegerIndicates the required gratuity behaviour for the retrieved transaction, which is set in the original transaction request (see POST/Transaction Parameters table in the Start Transaction section for details on which value sets which behaviour.
transactionExpiredBooleanIndicates if the retrieved transaction has expired before reaching a status of "Complete", this is dictatead by the current UTC time being checked against the expirationDate UTC date/time stamp.
If a transaction expires before it reaches axept® PRO it will no longer be accessible from the cloud by the solution, the status or the transaction will remain "Open" and the transCancelled value will remain false but this parameter will switch to true.
Note: A transaction expiring midway through a processing could affect features that rely on utilising the cloud to communicate back and forth between axept® PRO and the EPOS for decision making, prime example being signature verification from the EPOS. Ensure that you are setting at least 5 minutes on the expiry timestamp to allow adequate time for this.

Example GET /transaction Responses​

{
    "uti": "4865d11a-2cc8-432a-83f8-de199559eab6",
    "transType": "SALE",
    "transApproved": false,
    "transPartiallyApproved": false,
    "transCancelled": false,
    "amountTrans": 150,
    "amountGratuity": 0,
    "amountCashback": 0,
    "cvmSignatureRequired": false,
    "cvmPinVerified": false,
    "cardType": "Test",
    "createdDateTime": "2022-12-09T10:03:38.0461774Z",
    "merchantStoreId": 10223,
    "status": "Open"
}