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

Method

GET

URL

https://test-api.dnapayments.com/transaction/:id/search

“: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

Method

GET

URL

https://test-api.dnapayments.com/transaction/:id/search

“: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

Method

GET

URL

https://test-api.dnapayments.com/v2/transactions/:id/list

“: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

Method

GET

URL

https://test-api.dnapayments.com/v2/transactions/:id/list

“: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 Name

Data Type

Description

amount

Decimal

Total amount of the order including decimal places where applicable. ‘Whole’ amounts (e.g. “1”) on a GBP account represents £1.00.

authCode

String

Authorisation code issued for the transaction.

avsHouseNumberResult

String

Confirms the result of the Address Verification System (AVS) house number check.

Not Set	House Number check was not requested.
Not Checked	House Number could not be checked.
Matched	House Number matched.
Not Matched	House Number did not match.
Partial Match	House Number partially matched.

avsPostcodeResult

String

Confirms the result of the Address Verification System (AVS) post code check.

Not Set	Post Code check was not requested.
Not Checked	Post Code could not be checked.
Matched	Post Code matched.
Not Matched	Post Code did not match.
Partial Match	Post Code partially matched.

balance

String

Balance

cardExpiryDate

String

Expiry date for the card used in the transaction. Provided in the “MM/YY” format.

cardIssuingCountry

String

Country 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.

cardPanStarred

String

Starred PAN for the card used in the transaction - for example ************9909.

cardSchemeId

Integer

Optomany Card Scheme ID for the card used in the transaction.

cardSchemeName

String

Name of the Card scheme for the card used in the transaction.

cardTokenId

String

Optomany Token ID for the card presented.

charitableDonation

Decimal

Amount of any charitable donation awarded by the consumer during the transaction process.

cscResult

String

Confirms the result of the Card Security Code (CSC) validation check.

Not Set	CSC check was not requested.
Not Checked	CSC could not be checked.
Matched	CSC matched.
Not Matched	CSC did not match.

currency

String

Currency of the transaction.

GBP	Pound Sterling

String

Unique transaction ID. This ID should be stored as it is required for later transaction actions.

invoiceId

String

Order/invoice/transaction/basket number generated by the host website, as passed in the request.

payerAuthenticationResult

String

Result of the Payer Authentication process provided in the following format “enrolment result/authentication result”. The possible results are detailed below.

Enrollment		Authentication
Y	Successful	Y	Successful
N	Not enrolled	N	Not authenticated
A	Attempted	A	Attempted
U	Unable to check	U	Unable to authenticate
-	Not Attempted	-	Not Attempted

paymentMethod

String

Payment method used for the transaction.

card	Card payment
paypal	PayPal
applepay	Apple Pay
googlepay	Google Pay
paybybankapp	Pay by Bank App
ecospend	Open Banking (Ecospend)
Klarna	Klarna

payoutAmount

Decimal

Confirmation of the charge/settlement amount.

responseCode

String

Returned by the acquirer detailing the result of the transaction. A full list of Response Codes can be found here.

rrn

String

Unique reference allocated by Optomany to the authorisation.

transactionState

String

The current state of the transaction.

NEW	Transaction created; processing not started.
3D	Transaction is currently undergoing Payer Auth.
AUTH	Transaction is authorised.
FAILED	Transaction rejected due to an error.
REJECT	Transaction rejected by acquirer/issuer.
CHARGE	Transaction settled.
CANCEL	Transaction reversed.
REFUND	Transaction refunded.
TOKENIZED	Card Tokenised.
VERIFIED	Card verified.
CREDITED	Funds credited.
PROCESSING	Transaction being updated.
CREATED	Order was placed. (APM's only e.g. Paypal, Open Banking)
ABANDONED	Order abandoned. (APM's only e.g. Paypal, Open Banking)

transactionType

String

Type of transaction.

SALE	Sale
AUTH	Authorisation only
TOKENIZATION	Token registration request
RECURRING	For future use only
P2P	For 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 Name

Data Type

Description

accountId

String

Unique reference for the store processing the transaction, as passed in the request.

amount

Decimal

Total amount of the order including decimal places where applicable. ‘Whole’ amounts (e.g. “1”) on a GBP account represents £1.00.

currency

String

Currency of the transaction.

GBP	Pound Sterling

String

Unique transaction ID. This ID should be stored as it is required for later transaction actions.

invoiceId

String

Order/invoice/transaction/basket number generated by the host website, as passed in the request.

payoutAmount

Decimal

Confirmation of the charge/settlement amount.

paypalCaptureStatus

String

PayPal field = “capture_status_details”

COMPLETED	Funds have been credited to the payee’s PayPal account.
DECLINED	Funds could not be captured.
PARTIALLY_REFUNDED	An amount less than this captured payment’s amount was partially refunded to the payer.
PENDING	Funds have not yet credited to the payee’s PayPal account.
REFUNDED	An amount greater than or equal to this captured payment’s amount was refunded to the payer.

paypalEmail

String

PayPal email address used by the consumer.

paypalOrderStatus

String

PayPal field = “order_status”

CREATED	Order successfully created.
APPROVED	The customer approved the payment through the PayPal wallet or another form of guest or unbranded payment.
VOIDED	Order voided.
COMPLETED	The payment was authorized or the authorized payment was captured for the order.
PAYER_ACTION_REQUIRED	The order requires an action from the payer (e.g. 3DS authentication).

paypalPayerCountryCode

ISO 3166

Consumers country code.

paypalPayerID

String

PayPal allocated ID for the consumer.

paypalPayerName

String

Name of the consumer.

paypalSellerProtectionStatus

String

PayPal field = “seller_protection.status”

ELIGIBLE	PayPal 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_ELIGIBLE	PayPal balance remains intact if the customer claims that they did not receive an item.
NOT_ELIGIBLE	This transaction is not eligible for seller protection.

paypalSellerProtection
DisputeCategories

String

PayPal field = “dispute_category”

ITEM_NOT_RECEIVED	Payer paid for an item that they did not receive.
UNAUTHORIZED _TRANSACTION	The payer did not authorize the payment.

rrn

String

Unique reference allocated by Optomany to the authorisation.

transactionState

String

The current state of the transaction.

NEW	Transaction created; processing not started.
3D	Transaction is currently undergoing Payer Auth.
AUTH	Transaction is authorised.
FAILED	Transaction rejected due to an error.
REJECT	Transaction rejected by acquirer/issuer.
CHARGE	Transaction settled.
CANCEL	Transaction reversed.
REFUND	Transaction refunded.

transactionType

String

Type of transaction.

SALE	Sale.
AUTH	Authorisation only.
TOKENIZATION	Token registration request.
RECURRING	For future use only.
P2P	For future use only.

Paypal Response

paypalResponse

Field Name

Data Type

Description

create_time

String

Time and date of the PayPal transaction being created.

String

PayPal transaction Id.

intent

String

Confirming the intent used in the transaction, “Capture” or “Authorize”.

status

String

PayPal field = “order_status”

CREATED	Order successfully created.
APPROVED	The customer approved the payment through the PayPal wallet or another form of guest or unbranded payment.
VOIDED	Order voided.
COMPLETED	The payment was authorized or the authorized payment was captured for the order.
PAYER_ACTION_REQUIRED	The order requires an action from the payer (e.g. 3DS authentication).

update_time

String

Date and time of the last update to the PayPal order.

Paypal Response > Links

paypalResponse.links
Field Name	Data Type	Description
href	String	The complete target URL from PayPal.
method	String	The HTTP method required to make the related call.
rel	String	The 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 Name	Data Type	Description
reference_id	String	The merchant ID for the purchase unit.

Paypal Response > Purchase_Units > Amounts

paypalResponse.purchase_units.amounts
Field Name	Data Type	Description
currency_code	ISO 4217	Three-digit currency code for the transaction.
value	String	Transaction amount.

Paypal Response > Purchase_Units > Amount > Breakdown

paypalResponse.purchase_units.amount.breakdown

Field Name

Data Type

Description

handling

Array

Charges for handling.

currency_code	Three-digit currency code.
value	Value of the handling charges.

item_total

Array

Item totals.

currency_code	Three-digit currency code.
value	Value of the items.

shipping

Array

Charges for shipping.

currency_code	Three-digit currency code.
value	Value of the shipping charges.

tax_total

Array

Tax charges.

currency_code	Three-digit currency code.
value	Value of the tax charges.

Example Responses

Card Payment v1
Card Payment v2
Paypal Payment
Unsuccessful

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"
}

This example shows a £24 Sale followed by a £4 Refund.

Transaction Retrieval Response (Card)
[
    {
        "amount": 4,
        "authCode": "158171",
        "avsHouseNumberResult": "Not Checked",
        "avsPostcodeResult": "Not Checked",
        "balance": 20,
        "cardExpiryDate": "12/21",
        "cardIssuingCountry": "BRA",
        "cardPanStarred": "***************9909",
        "cardSchemeId": 8,
        "cardSchemeName": "MasterCard",
        "cardTokenId": "Te+q8PDfCk/ZuhiZrwUKd3HJT4L3jRS1bE83LvgAjO8fMQ==",
        "cscResult": "Not Checked",
        "currency": "GBP",
        "id": "598179a8-67ad-4ae9-a777-df8bfc38a4ae",
        "invoiceId": "OPT1633958133",
        "payerAuthenticationResult": "Y/A",
        "paymentMethod": "card",
        "payoutAmount": 24,
        "responseCode": "00",
        "rrn": "8bda31b1-58f9-4f49-a597-d213ba837b5f",
        "transactionState": "CHARGE",
        "transactionType": "SALE"
    },
    {
        "amount": 4,
        "authCode": "425128",
        "balance": 4,
        "currency": "GBP",
        "id": "ca71f55d-ad16-4a32-894d-0fa82ba77e0b",
        "invoiceId": "OPT1633958133",
        "paymentMethod": "card",
        "payoutAmount": 4,
        "responseCode": "00",
        "rrn": "db48812c-6618-4f16-a851-c59ea66fd4f2",
        "transactionState": "CREDITED",
        "transactionType": "ADJUSTMENT"
    }
]

Transaction Retrieval Response (Paypal)
{
  "accountId": "uuid000001",
  "amount": 65,
  "currency": "GBP",
  "id": "2d0f9d8d-e16e-4482-9629-6d1974c65bef",
  "invoiceId": "1609149596324",
  "payoutAmount": 65,
  "paypalCaptureStatus": "COMPLETED",
  "paypalEmail": "sb-9ieds2294744@personal.example.com",
  "paypalOrderStatus": "COMPLETED",
  "paypalPayerCountryCode": "GB",
  "paypalPayerID": "VFHQKQAR78CTY",
  "paypalPayerName": "John Doe",
  "paypalResponse": {
    "create_time": "2020-12-28T10:01:49Z",
    "id": "52D26809BG588383M",
    "intent": "CAPTURE",
    "links": [
      {
        "href": "https://api.sandbox.paypal.com/v2/checkout/orders/52D26809BG588383M",
        "method": "GET",
        "rel": "self"
      }
    ],
    "purchase_units": [
      {
        "amount": {
          "breakdown": {
            "handling": {
              "currency_code": "GBP",
              "value": "0.00"
            },
            "item_total": {
              "currency_code": "GBP",
              "value": "0.00"
            },
            "shipping": {
              "currency_code": "GBP",
              "value": "0.00"
            },
            "tax_total": {
              "currency_code": "GBP",
              "value": "0.00"
            }
          },
          "currency_code": "GBP",
          "value": "65.00"
        },
        "reference_id": "2d0f9d8d-e16e-4482-9629-6d1974c65bef"
      }
    ],
    "status": "COMPLETED",
    "update_time": "2020-12-28T10:02:20Z"
  },
  "paypalSellerProtectionDisputeCategories": "ITEM_NOT_RECEIVED,UNAUTHORIZED_TRANSACTION",
  "paypalSellerProtectionStatus": "ELIGIBLE",
  "rrn": "3YP57986VJ9197719",
  "transactionState": "CHARGE",
  "transactionType": "SALE"
}

"###
{
    "code": 2048,
    "message": "Transaction cannot be found. Please check input"
}

Transaction id​

invoiceId​

Version 1​

Transaction id​

invoiceId​

Version 2​

Transaction id​

invoiceId​

Transaction Retrieval Response - Card Payment​

Transaction Retrieval Response - Paypal​

Paypal Response​

Paypal Response > Links​

Paypal Response > Purchase_Units​

Paypal Response > Purchase_Units > Amounts​

Paypal Response > Purchase_Units > Amount > Breakdown​

Example Responses​

Transaction id

invoiceId

Version 1

Transaction id

invoiceId

Version 2

Transaction id

invoiceId

Transaction Retrieval Response - Card Payment

Transaction Retrieval Response - Paypal

Paypal Response

Paypal Response > Links

Paypal Response > Purchase_Units

Paypal Response > Purchase_Units > Amounts

Paypal Response > Purchase_Units > Amount > Breakdown

Example Responses