Date range queries

Last Updated: 18 November 2024 | Change Log

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.

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

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.
`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. 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. 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. Note 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.

Reponse

Response schema

_linksobjectrequired

links to the pages.

_links.selfobjectrequired

Self link to the page.

_links.self.hrefstring

First page as per the pageSize.

_links.nextobject

Next page link if the response contains more pages.

_embeddedobjectrequired

_embedded.paymentsArray of objects

Array of payments within the date range.

Response examples

{
    "_links": {
        "self": {
            "href": "/paymentQueries/payments?startDate=2024-04-28T21:30:20Z&endDate=2024-04-30T21:30:20Z"
        },
        "next": {
            "href": "/paymentQueries/payments?startDate=2024-04-28T21:30:20Z&endDate=2024-04-30T09:28:08.298Z&paymentId=cbe79beb-4555-4847-9789-c854cbc29f7e"
        }
    },
    "_embedded": {
        "payments": [
            {
                "timestamp": "2024-04-30T16:47:38.531Z",
                "transactionReference": "b00959d7-6bbf-49da-9d5e-a25fdd812447",
                "transactionType": "cardOnFile",
                "authorizationType": "authorization",
                "entity": "default",
                "paymentInstrument": {
                    "type": "card/plain+masked",
                    "card": {
                        "number": {
                            "last4Digits": "1000"
                        },
                        "brand": "visa",
                        "fundingType": "debit"
                    }
                },
                "value": {
                    "currency": "GBP",
                    "amount": 42
                },
                "_links": {
                    "self": {
                        "href": "/paymentQueries/payments/db6bb0dc-8930-4d65-a292-551a6bfab3c0"
                    }
                }
            },
            {
                "timestamp": "2024-04-30T16:23:55.677Z",
                "transactionReference": "135ab8fe-cdad-4362-ae48-9649b60493b0",
                "transactionType": "cardOnFile",
                "authorizationType": "authorization",
                "entity": "default",
                "paymentInstrument": {
                    "type": "card/plain"
                },
                "value": {
                    "currency": "GBP",
                    "amount": 42
                },
                "_links": {
                    "self": {
                        "href": "/paymentQueries/payments/9ac6c4b0-0722-4c69-9ac5-4eb37939af48"
                    }
                }
            },
            {
                "timestamp": "2024-04-30T16:11:05.230Z",
                "transactionReference": "52344b23-9641-402c-896d-78d7a586effd",
                "transactionType": "cardOnFile",
                "authorizationType": "authorization",
                "entity": "default",
                "paymentInstrument": {
                    "type": "card/plain"
                },
                "value": {
                    "currency": "GBP",
                    "amount": 42
                },
                "_links": {
                    "self": {
                        "href": "/paymentQueries/payments/9fb4b094-9f89-4e06-b92e-ff6b9336f385"
                    }
                }
            },
            {
                "timestamp": "2024-04-30T16:08:31.625Z",
                "transactionReference": "5a696f5f-38f6-4a3c-8d2d-bd043b401676",
                "transactionType": "cardOnFile",
                "authorizationType": "authorization",
                "entity": "default",
                "paymentInstrument": {
                    "type": "card/plain"
                },
                "value": {
                    "currency": "GBP",
                    "amount": 42
                },
                "_links": {
                    "self": {
                        "href": "/paymentQueries/payments/29e9b685-2c59-4484-9ac7-a45d3760c593"
                    }
                }
            },
            {
                "timestamp": "2024-04-30T09:28:08.298Z",
                "transactionReference": "1ca9d3e1-01f0-4ced-85eb-9028026f4a44",
                "transactionType": "oneTime",
                "authorizationType": "authorization",
                "entity": "default",
                "paymentInstrument": {
                    "type": "card/plain+masked",
                    "card": {
                        "number": {
                            "last4Digits": "4444"
                        },
                        "brand": "mastercard",
                        "fundingType": "credit"
                    }
                },
                "value": {
                    "currency": "GBP",
                    "amount": 650
                },
                "_links": {
                    "self": {
                        "href": "/paymentQueries/payments/cbe79beb-4555-4847-9789-c854cbc29f7e"
                    }
                }
            }
        ]
    }
}