Get a Transaction Metadata

Overview

The PayConex™ V4 API supports requesting transaction metadata using a transactionId value acquired at the time of processing a payment or initializing a transaction. This endpoint can also be used for generating a transaction report - either on-demand or at the end of the day.

Retrieving transaction metadata is straightforward: simply make a GET request using a transactionId.

The response provides a wealth of information for merchants and developers, including transaction type, description, customer data, shipping address, level 2 and level 3 data, transaction history (trace), amounts, and more. See the table below for a complete list and descriptions of these fields.

Another important benefit for developers to make use of is to watch over a transaction prior to processing after Initilizating a Transaction if a communication error or similar occurs.

📘

Data Projection

The PayConex™ V4 API implements projection, which means selecting and returning only the necessary fields from a JSON object instead of sending the entire dataset. Thereby, we are reducing the network bandwidth and memory usage for the merchant's integrations as their applications scale.

The V4 API filters out the data fields such as [], null, "", additionally applying the criteria for zero-amount values "0.00" with the exception of refundBalance including "0.00" regardless.

The projection also applies for entire fields if deemed redundant.

For example, the following fields will be filtered out altogether.

JSON

{
  "shippingAddress": {
    "address1": null,
    "address2": null,
    "city": null,
    "state": null,
    "zip": null,
    "country": null,
    "company": null,
    "recipient": null
  },
  "billingAddress": {
    "address1": null,
    "address2": null,
    "city": null,
    "state": null,
    "zip": null,
    "country": null,
    "company": null,
    "recipient": null
  },
  "level2": {
    "merchantReference": null,
    "orderId": null,
    "tax": null,
    "zip": null
  },
  "level3": {
    "status": "PENDING",
    "transactionSaleTaxRate": null,
    "merchantVatRegistrationNumber": null,
    "customerVatRegistrationNumber": null,
    "summaryCommodityCode": null,
    "discountAmount": null,
    "freightAmount": null,
    "dutyAmount": null,
    "destinationZip": null,
    "shipFromZip": null,
    "destinationCountryCode": null,
    "vatInvoiceRefNumber": null,
    "orderDate": null,
    "vatAmount": null,
    "vatRate": null,
    "alternateTaxAmount": null,
    "nationalTaxAmount": null
  },
  "healthcare": {
    "totalAmount": "0.00",
    "prescription": "0.00",
    "vision": "0.00",
    "dental": "0.00",
    "clinical": "0.00",
    "copay": "0.00",
    "transit": "0.00"
  },
  "threeDSecure": {
    "protectionEnabled": false,
    "eci": null,
    "status": null,
    "statusResult": null,
    "version": null,
    "token": null,
    "transactionId": null
  }
}

Resulting in:

{}

GET /api/v4/accounts/{accountId}/payments/{transactionId}

📘

Note

• {accountId} value in the path is the PayConex™ account ID number.
• {transactionId} value in the path is the transactionId to get.

*Required Scopes: pcx:payments:*, pcx:payments:read

Here is a sample response configuration:

{
  "transactionId": "000000046746",
  "status": "VOIDED",
  "timestamp": "2025-04-03T14:48:54.000000Z",
  "customer": {
    "name": "Alice",
    "billingAddress": {
      "address1": "address1",
      "address2": "address2",
      "city": "My City",
      "state": "MO",
      "zip": "90210",
      "country": "USA",
      "company": "Acme Inc."
    }
  },
  "shippingAddress": {
    "address1": "address1",
    "address2": "address2",
    "city": "My City",
    "state": "MO",
    "zip": "90210",
    "country": "USA",
    "company": "Acme Inc.",
    "recipient": "Alice Smith"
  },
  "trace": {
    "history": [
      {
        "action": "authorization",
        "requestId": "e77853d2-72a7-43f4-b2e5-32e611c42330",
        "correlationId": "5431fa60-c234-41f5-959e-71d1f3fa6d6f",
        "timestamp": "2025-04-03T09:45:35-05:00"
      },
      {
        "action": "capture",
        "requestId": "11002d0e-62ed-4fee-8bba-944e5b269912",
        "correlationId": "1e54498e-3d89-4033-99ff-756d63a32404",
        "timestamp": "2025-04-03T09:48:52-05:00"
      },
      {
        "action": "refund",
        "requestId": "6b8135d8-4061-4aab-8776-80ad99135911",
        "correlationId": "ff2f8b94-64ba-455c-a4b0-fa206f276383",
        "timestamp": "2025-04-03T10:09:24-05:00"
      }
    ],
    "networkTransactionId": "015093645028527G012"
  },
  "amounts": {
    "currency": "USD",
    "approved": "10.00",
    "requested": "10.00"
  },
  "auth": {
    "code": "OK0200",
    "processorMessage": "APPROVED",
    "message": "APPROVED",
    "avsResponseCode": "Y"
  },
  "card": {
    "name": "Alice",
    "last4": "1111",
    "expiry": "1225",
    "brand": "VISA"
  },
  "binData": {
    "program": "UNKNOWN"
  },
  "transactionType": "REFUND",
  "entryMode": "KEYED",
  "refundObject": {
    "refundBalance": "0.00",
    "refundIds": [
      "000000046766"
    ]
  }
}

👍

Note

For your security, transactions older than 18 months may be purged from our system.

Response Parameters

The following transaction metadata is intended for either reporting or debugging purposes.

🚧

Note

Despite the fact that most of these parameters are not present in the example above due to data projection, we cover all of their enumerations and use cases.

status

customer

billingAddress

This is the address associated with the customer's payment method. It is typically the address where the customer receives their credit card or bank statements.

shippingAddress

This is the address to which the goods or services purchased by the customer are delivered.

card

The summarized details about the card used to process the transaction.

level2

Level 2 data is an additional field supported for transaction processing.

For more details, see Level 2 Transaction Processing.

level3

Similar to Level 2 Data, Level 3 data is also an additional field supported for transaction processing. This data can be dynamically provided in a request using the parameters below or can be provided in a static form of Level 3 Profile. Level 3 data is also set with the Items.

For more details, see Level3 Profiles and Transaction Processing.

items

Also known as Line Item Detail, this particular property is used to provide detailed information about each individual item/purchase or service included in a Level 3 transaction. It helps in breaking down the transaction into its constituent parts, offering clarity and specificity for the Payment Processor. An item is set with Level 3 data so that each item is processed with the Level 3 data adjusted accordingly in the back end. With no level 3 data, items are only stored as additional transaction metadata.

amounts

healthcare

auth

When the transaction data is sent to the Processor for authorization, the PayConex™ Gateway populates this object with the key status updates:

• Authorization Confirmation: Confirms whether the transaction was approved or declined.

• Error Handling: Aids in troubleshooting and resolving issues with transactions.

• Customer Communication: Provides clear status updates to customers.

• Compliance and Reporting: Ensures accurate financial reporting and auditing.

message

Here is a comprehensive list of possible authorization messages.

avsResponseCode

cvv2ResponseCode

trace

history

The addition of the action type provides a clear record of modifications made to the transaction, making it easier to debug any issues that arise. It also enhances reporting capabilities by maintaining a detailed history of changes, allowing developers to audit and review the transaction lifecycle more effectively. This feature is particularly useful for identifying patterns, understanding the sequence of events, and ensuring compliance with data integrity standards.

action

clickToPayTraceData

The Mastercard-specific payment trace data for the Mastercard Click to Pay method of the Checkout Component.

shieldConexToken

Depending on the type of payment, this property contains the sensitive data tokenized into values and the Bluefin identifier by ShieldConex®.

Credit/Debit Card Transactions

ACH Transactions

refundObject

For the usage of this object in practice, see Refunding a Transaction.

binData

program

programCard

threeDSecure

3DS-related data indicating whether 3DS was enabled for that certain transaction including status, version, token, etc.