Overview

The Payment Lookup API enables you to query PaymentExpress directly to retrieve basic payment details and statuses in real time. It is a key part of your reconciliation and support workflows, giving you immediate visibility into the state of a payment.

This API is often used as a complement to Postbacks and the Payment Activity File. It helps your team verify individual transactions without waiting for scheduled reports and confirm that a payment was reversed successfully.

Your application searches using the paymentId from a successful payment. The results include key transaction attributes such as timestamps, tender types, fees, and current status.

This request uses the following format:

GET /api/v1/pay/payments/{paymentId}

Example Response

{
  "amounts": {
    "original": {
      "primary": "100.00",
      "fees": "2.50",
      "total": "102.50"
    },
    "current": {
      "primary": "100.00",
      "fees": "2.50",
      "total": "102.50"
    }
  },
  "timestamp": "2025-10-31T15:10:28.064Z",
  "items": [
    {
      "amounts": {
        "original": {
          "primary": "100.00",
          "fees": "2.50",
          "total": "102.50"
        },
        "current": {
          "primary": "100.00",
          "fees": "2.50",
          "total": "102.50"
        }
      },
      "itemId": "JDSKLGJSDG",
      "status": "charged",
      "fundCategory": "TAX",
      "department": "DMV"
    }
  ],
  "paymentChannel": "OTC",
  "tenderType": "CreditCard"
}

Error Handling

The Payment Lookup API provides clear error messages when a transaction cannot be found or retrieved.

Invalid or Unknown paymentId

The provided paymentId does not exist in PaymentExpress records.

Action: Verify that your application correctly captured the paymentId after the payment.

Authentication or Permissions Error

The credentials used for the lookup lack proper access or have expired.

Action: Confirm your authentication configuration or regenerate your credentials.

Network or Service Interruption

Temporary communication issues prevent the response from being delivered.

Action: Retry with exponential backoff and alert your support contact if the issue persists.

For more detailed information about the fields returned by a payment lookup, refer to the Look Up Payment API reference.