Transaction Retrieval

Transaction retrieval allows you to establish the status of any transaction processed via our Checkout solution. There are two ways to locate a transaction.

Transaction id

To retrieve details of a completed transaction the Transaction Id can be used. This is returned in the Payment Result as the id.

invoiceId

As an alternative to the Transaction Id it is also possible to locate a transaction using the invoiceId used in the Authentication and Payment Request messages. This allows for a transaction to be located where the result has not yet been received, perfect for scenarios where a transaction currently in progress requires checking.

The response remains unchanged whatever method is used.

Transaction Retrieval Version

Following partner feedback, we have added a second Transaction Retrieval endpoint, as detailed below. This version includes detail on any related transaction, as an array. It can be useful to determine advanced information on refunded or separately Authorised and Charged transactions.

Version 1

The method to request the search varies depending on the data being used.

Transaction id

MethodGET

“:id” is the id of the transaction whose status is required.

Example
https://test-api.dnapayments.com/transaction/1b1da354-d061-4f41-b251-f9cde86a9485/search

invoiceId

MethodGET

“:invoiceId” is the invoiceId of the transaction whose status is required.

Example
https://test-api.dnapayments.com/transaction/1623772434801/search?field=invoiceId

Version 2

The method to request the search varies depending on the data being used.

Transaction id

MethodGET

“:id” is the id of the transaction whose status is required.

Example
https://test-api.dnapayments.com/v2/transactions/1b1da354-d061-4f41-b251-f9cde86a9485/list

invoiceId

MethodGET

“:invoiceId” is the invoiceId of the transaction whose status is required.

Example
https://test-api.dnapayments.com/v2/transactions/1623772434801/list?field=invoiceId

Transaction Retrieval Response - Card Payment

note

Both version 1 and version 2 will return the same data, where applicable. In version 1, the below fields are presented as a single object for the chosen transaction. In version 2, there are multiple objects supplied in an array. See the Example Responses for more details.

Transaction Retrieval Response (Card)
Field NameData TypeDescription
amountDecimalTotal amount of the order including decimal places where applicable. ‘Whole’ amounts (e.g. “1”) on a GBP account represents £1.00.
authCodeStringAuthorisation code issued for the transaction.
avsHouseNumberResultStringConfirms the result of the Address Verification System (AVS) house number check.
NotSetHouse Number check was not requested.
NotCheckedHouse Number could not be checked.
MatchedHouse Number matched.
NotMatchedHouse Number did not match.
PartialMatchHouse Number partially matched.
avsPostcodeResultStringConfirms the result of the Address Verification System (AVS) post code check.
NotSetPost Code check was not requested.
NotCheckedPost Code could not be checked.
MatchedPost Code matched.
NotMatchedPost Code did not match.
PartialMatchPost Code partially matched.
balanceStringBalance
cardExpiryDateStringExpiry date for the card used in the transaction. Provided in the “MM/YY” format.
cardIssuingCountryStringCountry where the card was issued. This information will only be returned when this can be determined. This information is subject to change and as such we recommend only using this data as a guide.
cardPanStarredStringStarred PAN for the card used in the transaction - for example ************9909.
cardSchemeIdIntegerOptomany Card Scheme ID for the card used in the transaction.
cardSchemeNameStringName of the Card scheme for the card used in the transaction.
cardTokenIdStringOptomany Token ID for the card presented.
charitableDonationDecimalAmount of any charitable donation awarded by the consumer during the transaction process.
cscResultStringConfirms the result of the Card Security Code (CSC) validation check.
NotSetCSC check was not requested.
NotCheckedCSC could not be checked.
MatchedCSC matched.
NotMatchedCSC did not match.
currencyStringCurrency of the transaction.
GBPPound Sterling
idStringUnique transaction ID. This ID should be stored as it is required for later transaction actions.
invoiceIdStringOrder/invoice/transaction/basket number generated by the host website, as passed in the request.
payerAuthenticationResultStringResult of the Payer Authentication process provided in the following format “enrolment result/authentication result”. The possible results are detailed below.
EnrollmentAuthentication
YSuccessfulYSuccessful
NNot enrolledNNot authenticated
AAttemptedAAttempted
UUnable to checkUUnable to authenticate
-Not Attempted-Not Attempted
paymentMethodString

Payment method used for the transaction.

cardCard payment
paypalPayPal
applepayApple Pay
googlepayGoogle Pay
paybybankappPay by Bank App
ecospendOpen Banking (Ecospend)
KlarnaKlarna
payoutAmountDecimalConfirmation of the charge/settlement amount.
responseCodeStringReturned by the acquirer detailing the result of the transaction. A full list of Response Codes can be found here.
rrnStringUnique reference allocated by Optomany to the authorisation.
transactionStateStringThe current state of the transaction.
NEWTransaction created; processing not started.
3DTransaction is currently undergoing Payer Auth.
AUTHTransaction is authorised.
FAILEDTransaction rejected due to an error.
REJECTTransaction rejected by acquirer/issuer.
CHARGETransaction settled.
CANCELTransaction reversed.
REFUNDTransaction refunded.
transactionTypeStringType of transaction.
SALESale
AUTHAuthorisation only
TOKENIZATIONToken registration request
RECURRINGFor future use only
P2PFor future use only.
merchantCustomData

String

Base 64 Encoded
As supplied in the request by the integrator, supplied base 64 encoded.

Transaction Retrieval Response - Paypal

The below fields are also supplied when the transaction has been processed via that payment method.

Transaction Retrieval Response (Paypal)
Field NameData TypeDescription
accountIdStringUnique reference for the store processing the transaction, as passed in the request.
amountDecimalTotal amount of the order including decimal places where applicable. ‘Whole’ amounts (e.g. “1”) on a GBP account represents £1.00.
currencyStringCurrency of the transaction.
GBPPound Sterling
idStringUnique transaction ID. This ID should be stored as it is required for later transaction actions.
invoiceIdStringOrder/invoice/transaction/basket number generated by the host website, as passed in the request.
payoutAmountDecimalConfirmation of the charge/settlement amount.
paypalCaptureStatusStringPayPal field = “capture_status_details”
COMPLETEDFunds have been credited to the payee’s PayPal account.
DECLINEDFunds could not be captured.
PARTIALLY_REFUNDEDAn amount less than this captured payment’s amount was partially refunded to the payer.
PENDINGFunds have not yet credited to the payee’s PayPal account.
REFUNDEDAn amount greater than or equal to this captured payment’s amount was refunded to the payer.
paypalEmailStringPayPal email address used by the consumer.
paypalOrderStatusStringPayPal field = “order_status”
CREATEDOrder successfully created.
APPROVEDThe customer approved the payment through the PayPal wallet or another form of guest or unbranded payment.
VOIDEDOrder voided.
COMPLETEDThe payment was authorized or the authorized payment was captured for the order.
PAYER_ACTION_REQUIREDThe order requires an action from the payer (e.g. 3DS authentication).
paypalPayerCountryCodeISO 3166Consumers country code.
paypalPayerIDStringPayPal allocated ID for the consumer.
paypalPayerNameStringName of the consumer.
paypalSellerProtectionStatusStringPayPal field = “seller_protection.status”
ELIGIBLEPayPal balance remains intact if the customer claims that they did not receive an item or the account holder claims that they did not authorize the payment.
PARTIALLY_ELIGIBLEPayPal balance remains intact if the customer claims that they did not receive an item.
NOT_ELIGIBLEThis transaction is not eligible for seller protection.
paypalSellerProtection
DisputeCategories
StringPayPal field = “dispute_category”
ITEM_NOT_RECEIVEDPayer paid for an item that they did not receive.
UNAUTHORIZED
_TRANSACTION
The payer did not authorize the payment.
rrnStringUnique reference allocated by Optomany to the authorisation.
transactionStateStringThe current state of the transaction.
NEWTransaction created; processing not started.
3DTransaction is currently undergoing Payer Auth.
AUTHTransaction is authorised.
FAILEDTransaction rejected due to an error.
REJECTTransaction rejected by acquirer/issuer.
CHARGETransaction settled.
CANCELTransaction reversed.
REFUNDTransaction refunded.
transactionTypeStringType of transaction.
SALESale.
AUTHAuthorisation only.
TOKENIZATIONToken registration request.
RECURRINGFor future use only.
P2PFor future use only.

Paypal Response

paypalResponse
Field NameData TypeDescription
create_timeStringTime and date of the PayPal transaction being created.
idStringPayPal transaction Id.
intentStringConfirming the intent used in the transaction, “Capture” or “Authorize”.
statusStringPayPal field = “order_status”
CREATEDOrder successfully created.
APPROVEDThe customer approved the payment through the PayPal wallet or another form of guest or unbranded payment.
VOIDEDOrder voided.
COMPLETEDThe payment was authorized or the authorized payment was captured for the order.
PAYER_ACTION_REQUIREDThe order requires an action from the payer (e.g. 3DS authentication).
update_timeStringDate and time of the last update to the PayPal order.

Paypal Response > Links

paypalResponse.links
Field NameData TypeDescription
hrefStringThe complete target URL from PayPal.
methodStringThe HTTP method required to make the related call. 
relStringThe link relation type, which serves as an ID for a link that unambiguously describes the semantics of the link.
paypalResponse.links Usage

The above table values are only used by integrators who also have a direct integration with PayPal.

Paypal Response > Purchase_Units

paypalResponse.purchase_units
Field NameData TypeDescription
reference_idStringThe merchant ID for the purchase unit.

Paypal Response > Purchase_Units > Amounts

paypalResponse.purchase_units.amounts
Field NameData TypeDescription
currency_codeISO 4217Three-digit currency code for the transaction.
valueStringTransaction amount.

Paypal Response > Purchase_Units > Amount > Breakdown

paypalResponse.purchase_units.amount.breakdown
Field NameData TypeDescription
handlingArrayCharges for handling.
currency_codeThree-digit currency code.
valueValue of the handling charges.
item_totalArrayItem totals.
currency_codeThree-digit currency code.
valueValue of the items.
shippingArrayCharges for shipping.
currency_codeThree-digit currency code.
valueValue of the shipping charges.
tax_totalArrayTax charges.
currency_codeThree-digit currency code.
valueValue of the tax charges.

Example Responses

Transaction Retrieval Response (Card)
{
"accountId": "uuid000001",
"amount": 42.01,
"authCode": "123ABC",
"authDateTimeUTC": "2020-05-18T12:28:02.830039572Z",
"avsHouseNumberResult": "Matched",
"avsPostcodeResult": "Not Matched",
"cardExpiryDate": "06/20",
"cardIssuingCountry": "Brazil",
"cardPanStarred": "************9909",
"cardSchemeId": 8,
"cardSchemeName": "MasterCard",
"cardTokenId": "XZXIx6WNM+vyvTFBOlGObOZazHurxVN6Sgjxq+CYhVcfMQ==",
"cscResult": "Not Matched",
"currency": "GBP",
"id": "6fce7714-6109-40d8-b408-0c6700509b6a",
"invoiceId": "1589804887471",
"optomanyTerminalId": "31292612",
"payerAuthenticationResult": "Y/A",
"payoutAmount": 42.01,
"responseCode": "00",
"rrn": "8653/254/18052020122802000",
"transactionState": "REFUND",
"transactionType": "SALE"
}