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

## Date range queries

Query card payments within a specified date time range.

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

### Date range request

Provide a `startDate` and `endDate` to query all payments within a date range. The `startDate` cannot be older than one year.


`GET` `https://try.access.worldpay.com/paymentQueries/payments?startDate={startDate}&endDate={endDate}&pageSize={pageSize}`

#### Example

`GET` `https://try.access.worldpay.com/paymentQueries/payments?startDate=2023-02-12T21:30:20Z&endDate=2023-03-08T21:30:20Z&pageSize=20`

### Filter by currency

Query for payments within a specified date time range filtered by the requested currency.

`GET` `https://try.access.worldpay.com/paymentQueries/payments?startDate={startDate}&endDate={endDate}&pageSize={pageSize}&currency={currency}`

#### Example

`GET` `https://try.access.worldpay.com/paymentQueries/payments?startDate=2024-04-06T21:30:20Z&endDate=2024-04-30T21:30:20Z&pageSize=20&currency=GBP`

### Filter by minAmount, maxAmount

Query payments within a specified date time range filtered by the `minAmount` and `maxAmount` for a specific currency.

* `minAmount` - only payments with an amount above `minAmount` are included
* `maxAmount` - only payments with an amount below `maxAmount` are included


The amount uses an exponent rather than decimal delimiters.

If supplied:

* must be an integer greater than or equal to zero
* you must supply the currency parameter


br
`GET` `https://try.access.worldpay.com/paymentQueries/payments?startDate={startDate}&endDate={endDate}&pageSize={pageSize}&minAmount={minAmount}&maxAmount={maxAmount}&currency={currency}`

#### Example

`GET` `https://try.access.worldpay.com/paymentQueries/payments?startDate=2023-02-12T21:30:20Z&endDate=2023-03-08T21:30:20Z&pageSize=20&minAmount=250&maxAmount=300&&currency=GBP`

### Filter by last four digits

Query payments within a specified date time range filtered by the `last4Digits` of the card number.

`GET` `https://try.access.worldpay.com/paymentQueries/payments?startDate={startDate}&endDate={endDate}&pageSize={pageSize}&last4Digits={last4Digits}`

#### Example

`GET` `https://try.access.worldpay.com/paymentQueries/payments?startDate=2023-02-12T21:30:20Z&endDate=2023-03-08T21:30:20Z&pageSize=20&last4Digits=1111`

### Filter by payment event

Query payments within a specified date time range filtered by one or more `paymentEvents`.

`GET` `https://try.access.worldpay.com/paymentQueries/payments?startDate={startDate}&endDate={endDate}&pageSize={pageSize}&receivedEvents={receivedEvents}`

#### Example

`GET` `https://try.access.worldpay.com/paymentQueries/payments?startDate=2023-02-12T21:30:20Z&endDate=2023-03-08T21:30:20Z&pageSize=20&receivedEvents=authorizationRequested,refundRequested`

### Filter by entity references

Query payments within a specified date time range filtered by one or more `entityReferences` (also known as `entity`).

`GET` `https://try.access.worldpay.com/paymentQueries/payments?startDate={startDate}&endDate={endDate}&pageSize={pageSize}&entityReferences={entityReferences}`

#### Example

`GET` `https://try.access.worldpay.com/paymentQueries/payments?startDate=2023-02-12T21:30:20Z&endDate=2023-03-08T21:30:20Z&pageSize=20&entityReferences=ref1,ref2`

### Parameter descriptions

| Parameter | Required | Description |
|  --- | --- | --- |
| `startDate` | ✅ | An ISO 8601 date-time supplied as a string. Filters for payments that occurred after the specified date-time. Must be supplied alongside `endDate`. |
| `endDate` | ✅ | An ISO 8601 date-time supplied as a string. Filters for payments that occurred below the specified date-time. Must be supplied alongside `startDate`. |
| `pageSize` | ❌ | The maximum number of payments to be returned in the response. If supplied, must be a positive integer greater than 0 and less than or equal to 300. If not supplied, default value is 5. |
| `currency` | ❌ | The three digit [currency code](/products/reference/supported-countries-currencies#iso-currency-codes). |
| `minAmount` | ❌ | This is a whole number with an exponent, e.g. if exponent is two, 250 is 2.50. You can find the relevant exponent in our [currency table](/products/reference/supported-countries-currencies#iso-currency-codes). If supplied, must be an integer greater than or equal to 0. |
| `maxAmount` | ❌ | This is a whole number with an exponent, e.g. if exponent is two, 250 is 2.50. You can find the relevant exponent in our [currency table](/products/reference/supported-countries-currencies#iso-currency-codes). If supplied, must be an integer greater than or equal to 0. |
| `last4Digits` | ❌ | The last 4 digits of the card number. If supplied, must be a string with 4 digits. |
| `entityReferences` | ❌ | Merchant entity name. The request can be for a specific entity reference or can be grouped together as comma separated values.  You might have supplied this as `entity` in your original payment request.  |
| `receivedEvents` | ❌ | Name of the event. The request can be for a specific event name or can be grouped together as comma separated values. Default value is `All` which includes all events.Possible event values`authorizationRequested``authorizationSucceeded``authorizationRefused``authorizationFailed``authorizationTimedOut``saleRequested``saleSucceeded``saleRefused``saleFailed``saleTimedOut``cancellationRequested``cancellationRequestSubmitted``cancellationRequestSubmissionFailed``cancellationRequestSubmissionTimedOut``settlementRequested``settlementRequestSubmitted``settlementRequestSubmissionFailed``settlementRequestSubmissionTimedOut``refundRequested``refundRequestSubmitted``refundRequestSubmissionFailed``refundRequestSubmissionTimedOut``reversalRequested``reversalRequestSubmitted` |


### Response

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

### Response schema

### Response examples

dateRange query without pageSize
{
  "_links":{
    "self":{
      "href":"/paymentQueries/payments?startDate=2025-06-05T21:30:20Z&endDate=2025-07-08T21:30:20Z"
    },
    "next": {
      "href": "/paymentQueries/payments?startDate=2025-06-06T14:21:20Z&endDate=2025-06-15T09:28:08.298Z&paymentId=payvu0l-laj9bUfU3a2pRkq20"
    }      
  },
  "_embedded":{
    "payments":[
      {
        "timestamp":"2025-06-07T12:09:36.984Z",
        "transactionReference":"Memory265-13/08/1876",
        "transactionType":"oneTime",
        "authorizationType":"authorization",
        "entity":"default",
        "paymentInstrument":{
          "type":"card/plain"
        },
        "value":{
          "currency":"GBP",
          "amount":500
        },
        "_links":{
          "self":{
            "href":"/paymentQueries/payments/pay4u_lHl2jobU5S1T2pWkq10"
          }
        }
      },
      {
        "timestamp":"2025-06-07T12:05:01.134Z",
        "transactionReference":"Memory266",
        "transactionType":"oneTime",
        "authorizationType":"sale",
        "entity":"default",
        "issuer":{
          "authorizationCode":"948295"
        },
        "scheme":{
          "reference":"060720116005062"
        },
        "paymentInstrument":{
          "type":"card/plain+masked",
          "card":{
            "number":{
              "last4Digits":"1111",
              "cardBin":"444433"
            },
            "brand":"visa",
            "expiryDate":{
              "month":5,
              "year":2035
            },
            "fundingType":"credit",
            "issuerName":"A Card Issuer",
            "paymentAccountReference":"Q1HJZ28RKA1EBL470G9XYG90R5D3E",
            "category":"consumer"
          }
        },
        "value":{
          "currency":"GBP",
          "amount":500
        },
        "_links":{
          "self":{
            "href":"/paymentQueries/payments/pay3f7oMDb3cCr2z-e_5L4vt0"
          }
        }
      },
      {
        "timestamp":"2025-06-10T10:22:19.844Z",
        "transactionReference":"897b8357-0c45-4529-93ce-136dbeac562f",
        "transactionType":"oneTime",
        "authorizationType":"authorization",
        "entity":"default",
        "issuer":{
          "authorizationCode":"478296"
        },
        "scheme":{
          "reference":"060720116005062"
        },
        "paymentInstrument":{
          "type":"card/network+masked",
          "card":{
            "number":{
              "last4Digits":"9224",
              "cardBin":"483196"
            },
            "brand":"visa",
            "expiryDate":{
              "month":12,
              "year":2028
            },
            "countryCode":"SG",
            "fundingType":"debit",
            "issuerName":"Helios Bank",
            "paymentAccountReference":"A00JZ28RKA5EBG470G4AYGV0R5D3D",
            "category":"consumer"
          }
        },
        "value":{
          "currency":"GBP",
          "amount":250
        },
        "_links":{
          "self":{
            "href":"/paymentQueries/payments/paydf5o-Db5cGREs-vT7L4vC0"
          }
        }
      },
      {
        "timestamp":"2025-06-13T10:21:28.717Z",
        "transactionReference":"93c3df1f-d5c9-4b6b-8f76-8334bae9b0e4",
        "transactionType":"oneTime",
        "authorizationType":"authorization",
        "entity":"default",
        "issuer":{
          "authorizationCode":"737147"
        },
        "scheme":{
          "reference":"060720116005062"
        },
        "paymentInstrument":{
          "type":"card/network+masked",
          "card":{
            "number":{
              "last4Digits":"9224",
              "cardBin":"483196"
            },
            "brand":"visa",
            "expiryDate":{
              "month":12,
              "year":2028
            },
            "countryCode":"SG",
            "fundingType":"debit",
            "issuerName":"Helios Bank",
            "paymentAccountReference":"A00JZ28RKA5EBG470G4AYGV0R5D3D",
            "category":"consumer"
          }
        },
        "value":{
          "currency":"GBP",
          "amount":250
        },
        "_links":{
          "self":{
            "href":"/paymentQueries/payments/2a4d37cb-03b1-48c0-a588-dc1a00a83c5f"
          }
        }
      },
      {
        "timestamp":"2025-06-14T10:21:12.755Z",
        "transactionReference":"75c40ad1-3945-4c48-a6ad-043e346072be",
        "transactionType":"oneTime",
        "authorizationType":"authorization",
        "entity":"default",
        "issuer":{
          "authorizationCode":"995350"
        },
        "scheme":{
          "reference":"060720116005062"
        },
        "paymentInstrument":{
          "type":"card/network+masked",
          "card":{
            "number":{
              "last4Digits":"9224",
              "cardBin":"483196"
            },
            "brand":"visa",
            "expiryDate":{
              "month":12,
              "year":2028
            },
            "countryCode":"SG",
            "fundingType":"debit",
            "issuerName":"Helios Bank",
            "paymentAccountReference":"A00JZ28RKA5EBG470G4AYGV0R5D3D",
            "category":"consumer"
          }
        },
        "value":{
          "currency":"GBP",
          "amount":250
        },
        "_links":{
          "self":{
            "href":"/paymentQueries/payments/e638cfbd-5df9-40da-9996-938bb636e299"
          }
        }
      }
    ]
  }
}

dateRange query with pageSize
{
  "_links":{
    "self":{
      "href":"/paymentQueries/payments?startDate=2025-06-05T21:30:20Z&endDate=2025-07-08T21:30:20Z&pageSize=3"
    },
    "next": {
      "href": "/paymentQueries/payments?startDate=2025-06-13T10:21:28.717Z&endDate=2025-06-15T09:28:08.298Z&paymentId=2a4d37cb-03b1-48c0-a588-dc1a00a83c5f"
    }      
  },
  "_embedded":{
    "payments":[
      {
        "timestamp":"2025-06-07T12:09:36.984Z",
        "transactionReference":"Memory265-13/08/1876",
        "transactionType":"oneTime",
        "authorizationType":"authorization",
        "entity":"default",
        "paymentInstrument":{
          "type":"card/plain"
        },
        "value":{
          "currency":"GBP",
          "amount":500
        },
        "_links":{
          "self":{
            "href":"/paymentQueries/payments/pay4u_lHl2jobU5S1T2pWkq10"
          }
        }
      },
      {
        "timestamp":"2025-06-07T12:05:01.134Z",
        "transactionReference":"Memory266",
        "transactionType":"oneTime",
        "authorizationType":"sale",
        "entity":"default",
        "issuer":{
          "authorizationCode":"948295"
        },
        "scheme":{
          "reference":"060720116005062"
        },
        "paymentInstrument":{
          "type":"card/plain+masked",
          "card":{
            "number":{
              "last4Digits":"1111",
              "cardBin":"444433"
            },
            "brand":"visa",
            "expiryDate":{
              "month":5,
              "year":2035
            },
            "fundingType":"credit",
            "issuerName":"A Card Issuer",
            "paymentAccountReference":"Q1HJZ28RKA1EBL470G9XYG90R5D3E",
            "category":"consumer"
          }
        },
        "value":{
          "currency":"GBP",
          "amount":500
        },
        "_links":{
          "self":{
            "href":"/paymentQueries/payments/pay3f7oMDb3cCr2z-e_5L4vt0"
          }
        }
      },
      {
        "timestamp":"2025-06-10T10:22:19.844Z",
        "transactionReference":"897b8357-0c45-4529-93ce-136dbeac562f",
        "transactionType":"oneTime",
        "authorizationType":"authorization",
        "entity":"default",
        "issuer":{
          "authorizationCode":"478296"
        },
        "scheme":{
          "reference":"060720116005062"
        },
        "paymentInstrument":{
          "type":"card/network+masked",
          "card":{
            "number":{
              "last4Digits":"9224",
              "cardBin":"483196"
            },
            "brand":"visa",
            "expiryDate":{
              "month":12,
              "year":2028
            },
            "countryCode":"SG",
            "fundingType":"debit",
            "issuerName":"Helios Bank",
            "paymentAccountReference":"A00JZ28RKA5EBG470G4AYGV0R5D3D",
            "category":"consumer"
          }
        },
        "value":{
          "currency":"GBP",
          "amount":250
        },
        "_links":{
          "self":{
            "href":"/paymentQueries/payments/paydf5o-Db5cGREs-vT7L4vC0"
          }
        }
      }
    ]
  }
}

dateRange query with currency filter
{
  "_links":{
    "self":{
      "href":"/paymentQueries/payments?startDate=2025-06-05T21:30:20Z&endDate=2025-07-08T21:30:20Z&currency=GBP&pageSize=2"
    },
    "next": {
      "href": "/paymentQueries/payments?startDate=2025-06-06T14:21:20Z&endDate=2025-06-15T09:28:08.298Z&paymentId=payvu0l-laj9bUfU3a2pRkq20"
    }      
  },
  "_embedded":{
    "payments":[
      {
        "timestamp":"2025-06-07T12:05:01.134Z",
        "transactionReference":"Memory266",
        "transactionType":"oneTime",
        "authorizationType":"sale",
        "entity":"default",
        "issuer":{
          "authorizationCode":"948295"
        },
        "scheme":{
          "reference":"060720116005062"
        },
        "paymentInstrument":{
          "type":"card/plain+masked",
          "card":{
            "number":{
              "last4Digits":"1111",
              "cardBin":"444433"
            },
            "brand":"visa",
            "expiryDate":{
              "month":5,
              "year":2035
            },
            "fundingType":"credit",
            "issuerName":"A Card Issuer",
            "paymentAccountReference":"Q1HJZ28RKA1EBL470G9XYG90R5D3E",
            "category":"consumer"
          }
        },
        "value":{
          "currency":"GBP",
          "amount":500
        },
        "_links":{
          "self":{
            "href":"/paymentQueries/payments/pay3f7oMDb3cCr2z-e_5L4vt0"
          }
        }
      },
      {
        "timestamp":"2025-06-10T10:22:19.844Z",
        "transactionReference":"897b8357-0c45-4529-93ce-136dbeac562f",
        "transactionType":"oneTime",
        "authorizationType":"authorization",
        "entity":"default",
        "issuer":{
          "authorizationCode":"478296"
        },
        "scheme":{
          "reference":"060720116005062"
        },
        "paymentInstrument":{
          "type":"card/network+masked",
          "card":{
            "number":{
              "last4Digits":"9224",
              "cardBin":"483196"
            },
            "brand":"visa",
            "expiryDate":{
              "month":12,
              "year":2028
            },
            "countryCode":"SG",
            "fundingType":"debit",
            "issuerName":"Helios Bank",
            "paymentAccountReference":"A00JZ28RKA5EBG470G4AYGV0R5D3D",
            "category":"consumer"
          }
        },
        "value":{
          "currency":"GBP",
          "amount":250
        },
        "_links":{
          "self":{
            "href":"/paymentQueries/payments/paydf5o-Db5cGREs-vT7L4vC0"
          }
        }
      }
    ]
  }
}

error
{
    "errorName": "startDateTooOld",
    "message": "Provided start date must not be older than 1 year."
}