**Last updated**: 17 October 2025 | [**Change log**](/products/payment-queries/changelog/)

# Transaction reference queries

Provide a `transactionReference` to find the matching card payment.

Note
The API returns data for payments processed after 25 June 2024. For payments processed before then, you can [query for historical payments](/products/payment-queries/query-archive).

## Request

The transaction reference is a **unique** reference generated by you. It is used to identify a payment throughout its lifecycle. We highly recommend that you save the `transactionReference` of a payment and use it to query payments when needed.


`GET` `https://try.access.worldpay-bsh.securedataplatform.com/paymentQueries/payments?transactionReference={transactionReference}`

### Example

`GET` `https://try.access.worldpay-bsh.securedataplatform.com/paymentQueries/payments?transactionReference=Memory265-13/08/1876`

### Parameter description

| Parameter | Required | Description |
|  --- | --- | --- |
| `transactionReference` | ✅ | A **unique** reference generated by you. It is used to identify a payment throughout its lifecycle. |


## Response

The response contains summary information about the payment associated with the `transactionReference`. For detailed information about a payment you should run a [query using the `paymentId`](/products/payment-queries/retrieve-by-payment-id).

### Response schema


```json
{
  "$ref": "#/components/schemas/pq_querybydaterange_200_response",
  "components": {
    "schemas": {
      "paymentId": {
        "maxLength": 36,
        "minLength": 25,
        "pattern": "^[A-Za-z0-9_-]*$",
        "type": "string",
        "description": "Unique identifier generated by us for a single payment. Generated at authorization, and maintained through successive payment actions.",
        "example": "pay4u_lHl2jobU5S1T2pWkq10"
      },
      "lastEvent": {
        "type": "string",
        "description": "The last event received for the payment",
        "example": "authorizationSucceeded",
        "enum": [
          "authorizationRequested",
          "authorizationSucceeded",
          "authorizationRefused",
          "authorizationFailed",
          "authorizationTimedOut",
          "saleRequested",
          "saleSucceeded",
          "saleRefused",
          "saleFailed",
          "saleTimedOut",
          "settlementRequested",
          "settlementRequestSubmitted",
          "settlementRequestSubmissionFailed",
          "settlementRequestSubmissionTimedOut",
          "refundRequested",
          "refundRequestSubmitted",
          "refundRequestSubmissionFailed",
          "refundRequestSubmissionTimedOut",
          "cancellationRequested",
          "cancellationRequestSubmitted",
          "cancellationRequestSubmissionFailed",
          "cancellationRequestSubmissionTimedOut",
          "reversalRequested",
          "reversalRequestSubmitted",
          "reversalRequestSubmissionFailed",
          "reversalRequestSubmissionTimedOut"
        ],
        "x-enumDescriptions": {
          "authorizationRequested": "Worldpay has received your authorization request.",
          "authorizationSucceeded": "Your authorization request was successfully approved by the card issuer.",
          "authorizationRefused": "Your authorization request was refused by the card issuer.",
          "authorizationFailed": "Your authorization request failed.",
          "authorizationTimedOut": "Your authorization request timed out.",
          "saleRequested": "Worldpay has received your sale request.",
          "saleSucceeded": "Your sale request was successfully approved by the card issuer.",
          "saleRefused": "Your sale request was refused by the card issuer.",
          "saleFailed": "Your sale request failed.",
          "saleTimedOut": "Your sale request timed out.",
          "settlementRequested": "Worldpay has received your settlement request.",
          "settlementRequestSubmitted": "Your settlement request was successfully sent for processing.",
          "settlementRequestSubmissionFailed": "Your settlement request failed.",
          "settlementRequestSubmissionTimedOut": "Your settlement request timed out.",
          "refundRequested": "Worldpay has received your refund request.",
          "refundRequestSubmitted": "Your refund request was successfully sent for processing.",
          "refundRequestSubmissionFailed": "We failed to process your refund request.",
          "refundRequestSubmissionTimedOut": "Your refund request timed out.",
          "cancellationRequested": "Worldpay has received your cancellation request.",
          "cancellationRequestSubmitted": "Your cancellation request was successfully sent for processing.",
          "cancellationRequestSubmissionFailed": "Your cancellation request failed.",
          "cancellationRequestSubmissionTimedOut": "Your cancellation request timed out.",
          "reversalRequested": "Worldpay has received your reversal request.",
          "reversalRequestSubmitted": "Your reversal request was successfully sent for processing.",
          "reversalRequestSubmissionFailed": "Your reversal request failed.",
          "reversalRequestSubmissionTimedOut": "Your reversal request timed out."
        }
      },
      "pq_querybydaterange_200_response": {
        "required": [
          "_links",
          "_embedded"
        ],
        "type": "object",
        "properties": {
          "_links": {
            "required": [
              "self"
            ],
            "type": "object",
            "description": "links to the pages.",
            "properties": {
              "self": {
                "type": "object",
                "description": "Self link to the page.",
                "properties": {
                  "href": {
                    "type": "string",
                    "description": "First page as per the pageSize."
                  }
                }
              },
              "next": {
                "type": "object",
                "description": "Next page link if the response contains more pages.",
                "properties": {
                  "href": {
                    "type": "string",
                    "description": "Second page as per the pageSize."
                  }
                }
              }
            }
          },
          "_embedded": {
            "type": "object",
            "properties": {
              "payments": {
                "type": "array",
                "required": [
                  "timestamp",
                  "transactionReference",
                  "entity"
                ],
                "description": "Array of payments within the date range.",
                "items": {
                  "type": "object",
                  "properties": {
                    "timestamp": {
                      "type": "string",
                      "description": "Payment initial authorization time."
                    },
                    "paymentId": {
                      "$ref": "#/components/schemas/paymentId"
                    },
                    "transactionReference": {
                      "type": "string",
                      "description": "A unique reference generated by you, used to identify a payment throughout its lifecycle."
                    },
                    "narrative": {
                      "type": "object",
                      "description": "An object that contains identification and further details of the merchant.",
                      "properties": {
                        "line1": {
                          "type": "string",
                          "description": "First line of text that appears on your customer's statement."
                        },
                        "line2": {
                          "type": "string",
                          "description": "Second line of text that appears on your customer's statement."
                        }
                      }
                    },
                    "transactionType": {
                      "enum": [
                        "oneTime",
                        "cardOnFile",
                        "recurring"
                      ],
                      "type": "string",
                      "description": "An object that contains transaction type."
                    },
                    "authorizationType": {
                      "enum": [
                        "authorization",
                        "sale"
                      ],
                      "type": "string",
                      "description": "An object that contains authorization type."
                    },
                    "entity": {
                      "type": "string",
                      "description": "Merchant entity name."
                    },
                    "lastEvent": {
                      "$ref": "#/components/schemas/lastEvent"
                    },
                    "scheme": {
                      "required": [
                        "reference"
                      ],
                      "type": "object",
                      "description": "An object containing information returned by the card scheme.",
                      "properties": {
                        "reference": {
                          "type": "string",
                          "description": "The reference returned by the scheme for this particular payment authorization.",
                          "example": "MCCOLXT1C0104  "
                        }
                      }
                    },
                    "issuer": {
                      "required": [
                        "authorizationCode"
                      ],
                      "type": "object",
                      "description": "An object containing information returned by the issuer.",
                      "properties": {
                        "authorizationCode": {
                          "pattern": "^[a-zA-Z0-9]+$",
                          "type": "string",
                          "description": "A code returned by the card issuer for a successful authorization. Used in reconciliation and dispute management.",
                          "example": "T31306"
                        }
                      }
                    },
                    "paymentInstrument": {
                      "type": "object",
                      "description": "The payment instrument supplied in the authorization request.",
                      "properties": {
                        "type": {
                          "type": "string",
                          "enum": [
                            "card/plain",
                            "card/network",
                            "card/networkToken",
                            "card/networkToken+applepay",
                            "card/networkToken+googlepay",
                            "card/plain+masked"
                          ],
                          "description": "The type of payment instrument supplied in the authorization request."
                        },
                        "card": {
                          "type": "object",
                          "description": "An object that contains information about the card used.",
                          "properties": {
                            "number": {
                              "type": "object",
                              "description": "An object that contains information about the card number.",
                              "properties": {
                                "cardBin": {
                                  "pattern": "^[0-9*]+$",
                                  "type": "string",
                                  "description": "The card BIN (Bank Identification Number) is the first 6 or 8 digits of the card number, and can be used to identify the card issuer, the card brand(s) (eg Visa, Cartes Bancaires), and the country. Card BINs are used to route transactions, check card capabilities, and in fraud assessments.",
                                  "example": "444433"
                                },
                                "last4Digits": {
                                  "pattern": "^[0-9*]+$",
                                  "type": "string",
                                  "description": "The last four digits of the card. Some characters may be obfuscated with a `*` if the PAN length is less than 16 characters.",
                                  "example": "1111"
                                }
                              }
                            },
                            "category": {
                              "type": "string",
                              "description": "Whether the card is classed as a consumer card or a card for commercial use.",
                              "enum": [
                                "commercial",
                                "consumer"
                              ]
                            },
                            "countryCode": {
                              "maxLength": 2,
                              "minLength": 2,
                              "pattern": "^[A-Z]+$",
                              "type": "string",
                              "description": "The [ISO 3166-1 Alpha-2 format](/products/reference/supported-countries-currencies#iso-country-codes) country code that the card was issued in. May return `N/A` where the country is unknown.",
                              "example": "GB"
                            },
                            "expiryDate": {
                              "type": "object",
                              "description": "The expiry date of the card or network token (where the supplied paymentInstrument was `card/wallet+applepay`, `card/wallet+googlepay`, `card/networkToken`, `card/networkToken+applepay` or `card/networkToken+googlepay`).",
                              "properties": {
                                "month": {
                                  "type": "integer"
                                },
                                "year": {
                                  "type": "integer"
                                }
                              }
                            },
                            "issuerName": {
                              "type": "string",
                              "description": "The name of the card issuer.",
                              "example": "AN ISSUING BANK LTD"
                            },
                            "fundingType": {
                              "type": "string",
                              "description": "How the card is funded.",
                              "enum": [
                                "credit",
                                "debit",
                                "prepaid",
                                "chargeCard",
                                "deferredDebit"
                              ]
                            },
                            "brand": {
                              "type": "string",
                              "description": "The card brand that the transaction was processed with. Sometimes referred to as the network or scheme.",
                              "example": "visa"
                            },
                            "paymentAccountReference": {
                              "type": "string",
                              "description": "The payment account reference (PAR) is a non-financial reference that uniquely identifies the underlying cardholder account. This allows you to correlate payments made from the same account with differing instruments (e.g. `card/plain` and `card/wallet+applepay`), where the same account funds the transaction. A PAR cannot be used to initiate a payment.",
                              "example": "Q1HJZ28RKA1EBL470G9XYG90R5D3E"
                            }
                          }
                        }
                      }
                    },
                    "value": {
                      "required": [
                        "amount",
                        "currency"
                      ],
                      "type": "object",
                      "description": "An object that contains payment amount and currency.",
                      "properties": {
                        "amount": {
                          "type": "integer",
                          "description": "This is a whole number including the currency exponent (e.g. GBP has an exponent of 2, so for £2.50 supply:`250`)."
                        },
                        "currency": {
                          "type": "string",
                          "description": "The 3 digit currency code."
                        }
                      }
                    },
                    "_links": {
                      "required": [
                        "self"
                      ],
                      "type": "object",
                      "description": "link to retrieveByPaymentId.",
                      "properties": {
                        "self": {
                          "type": "object",
                          "description": "Self link to retrieveByPaymentId.",
                          "properties": {
                            "href": {
                              "type": "string",
                              "description": "RetrieveByPaymentId provides event history and next action links."
                            }
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}
```

### Response examples


```json
{
  "_links":{
    "self":{
      "href":"/paymentQueries/payments?transactionReference=myTransactionRef"
    }
  },
  "_embedded":{
    "payments":[
      {
        "timestamp":"2025-07-07T12:42:49.180Z",
        "paymentId":"pay8-y92Hu8vA-m30qa4C_9w0",
        "transactionReference":"myTransactionRef",
        "narrative":{
          "line1":"narrativeline1",
          "line2":"narrativeline2"
        },
        "transactionType":"cardOnFile",
        "authorizationType":"authorization",
        "lastEvent": "authorizationSucceeded",
        "entity":"default",
        "issuer":{
          "authorizationCode":"A12345"
        },
        "scheme":{
          "reference":"060720116005062"
        },
        "updatedPaymentInstrument":{
          "type":"card/plain+masked",
          "card":{
            "number":{
              "last4Digits":"0275",
              "cardBin":"478901"
            },
            "brand":"visa",
            "expiryDate":{
              "month":10,
              "year":2036
            },
            "countryCode":"GB",
            "fundingType":"credit"
          },
          "accountUpdaterMessage":"The account number was changed"
        },
        "paymentInstrument":{
          "type":"card/plain",
          "card":{
            "number":{
              "last4Digits":"0274",
              "cardBin":"478900"
            },
            "brand":"visa",
            "expiryDate":{
              "month":9,
              "year":2035
            },
            "countryCode":"GB",
            "fundingType":"debit",
            "issuerName":"A Card Issuer",
            "paymentAccountReference":"Q1HJZ28RKA1EBL470G9XYG90R5D3E",
            "category":"consumer"
          }
        },
        "value":{
          "currency":"GBP",
          "amount":1120
        },
        "_links":{
          "self":{
            "href":"/paymentQueries/payments/pay8-y92Hu8vA-m30qa4C_9w0"
          }
        }
      }
    ]
  }
}
```

## Historical payments

If the payment was processed before 25 June 2024, you must query our [historical payments library](/products/payment-queries/query-archive).

You receive a next action link in the response. Add your `entityReference` and `transactionReference` to query historical payments.

### Example


```json
{
    "_links": {
        "self": {
            "href": "/paymentQueries/payments?transactionReference=demo-test1"
        },
        "paymentQueries:queryArchive": {
            "href": "/paymentQueries/archivedPayments?transactionReference=demo-test1&entityReference={entityReference}",
            "templated": true
        }
    },
    "_embedded": {
        "payments": []
    }
}
```