# Query payments

Query payments within a specified date time range.
These payments can be filtered by currency, minAmount, maxAmount, last4Digits & receivedEvents.
The API returns data for payments processed after 25 June 2024. For payments processed before then use our [query for historical payments](/products/payment-queries/@v1/query-archive.md).

Endpoint: GET /paymentQueries/payments
Version: 1
Security: BasicAuth

## Security:

  - `BasicAuth` (unknown)
    http basic

## Query parameters:

  - `startDate` (string, required)
    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` (string, required)
    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` (integer)
    The maximum number of payments to be returned in the response (max 300).

  - `currency` (string)
    The three digit currency code.

  - `minAmount` (integer)
    This is a whole number including the currency exponent (e.g. GBP has an exponent of 2, so for £2.50 supply:`250`).

  - `maxAmount` (integer)
    This is a whole number including the currency exponent (e.g. GBP has an exponent of 2, so for £2.50 supply:`250`).

  - `last4Digits` (string)
    The last four digits of the card number.

  - `entityReferences` (string)
    Your entity reference(s).

  - `receivedEvents` (string)
    Name of the event.

  - `transactionReference` (string)
    A unique reference generated by you, used to identify a payment throughout its lifecycle. This shouldn't be used in conjunction with the above fields. Use it as a single parameter to query data.

  - `orderReference` (string)
    A reference, generated by you, that you can apply to one or more payments according to your business needs. You may reuse the same reference across multiple payments, for example where:
- the total amount for a single order is split across multiple payments
- you use a single reference for each payment in a recurring agreement or split shipment scenario 

This shouldn't be used in conjunction with the above fields. Use it as a single parameter to query data.

**Note**: Querying by orderReference returns data for payments processed after 20 August 2026.

## Header parameters:

  - `Accept` (string, required)

## Response 200:

  - `200` (unknown)
    Summary information of list of payments within a specified date range.

## Response 200 fields (application/vnd.worldpay.payment-queries-v1.hal+json):

  - `_links` (object, required)
    links to the pages.

  - `_links.self` (object, required)
    Self link to the page.

  - `_links.self.href` (string)
    First page as per the pageSize.

  - `_links.next` (object)
    Next page link if the response contains more pages.

  - `_links.next.href` (string)
    Second page as per the pageSize.

  - `_embedded` (object, required)

  - `_embedded.payments` (array)
    Array of payments within the date range.

  - `_embedded.payments.timestamp` (string)
    Payment initial authorization time.

  - `_embedded.payments.paymentId` (string)
    Unique identifier generated by us for a single payment. Generated at authorization, and maintained through successive payment actions.
    Example: pay4u_lHl2jobU5S1T2pWkq10

  - `_embedded.payments.transactionReference` (string)
    A unique reference, generated by you, used to identify a payment throughout its lifecycle.

  - `_embedded.payments.orderReference` (string)
    A reference, generated by you, that you can apply to one or more payments according to your business needs. You may reuse the same reference across multiple payments.

  - `_embedded.payments.narrative` (object)
    An object that contains identification and further details of the merchant.

  - `_embedded.payments.narrative.line1` (string)
    First line of text that appears on your customer's statement.

  - `_embedded.payments.narrative.line2` (string)
    Second line of text that appears on your customer's statement.

  - `_embedded.payments.transactionType` (string)
    An object that contains transaction type.
    Enum: "oneTime", "cardOnFile", "recurring"

  - `_embedded.payments.authorizationType` (string)
    An object that contains authorization type.
    Enum: "authorization", "sale"

  - `_embedded.payments.entity` (string)
    Merchant entity name.

  - `_embedded.payments.lastEvent` (string)
    The last event received for the payment
    Enum: "authorizationRequested", "authorizationSucceeded", "authorizationRefused", "authorizationFailed", "authorizationTimedOut", "incrementalAuthorizationRequested", "incrementalAuthorizationSucceeded", "incrementalAuthorizationRefused", "incrementalAuthorizationFailed", "incrementalAuthorizationTimedOut", "saleRequested", "saleSucceeded", "saleRefused", "saleFailed", "saleTimedOut", "settlementRequested", "settlementRequestSubmitted", "settlementRequestSubmissionFailed", "settlementRequestSubmissionTimedOut", "refundRequested", "refundRequestSubmitted", "refundRequestSubmissionFailed", "refundRequestSubmissionTimedOut", "cancellationRequested", "cancellationRequestSubmitted", "cancellationRequestSubmissionFailed", "cancellationRequestSubmissionTimedOut", "reversalRequested", "reversalRequestSubmitted", "reversalRequestSubmissionFailed", "reversalRequestSubmissionTimedOut"

  - `_embedded.payments.scheme` (object)
    An object containing information returned by the card scheme.

  - `_embedded.payments.scheme.reference` (string, required)
    The reference returned by the scheme for this particular payment authorization.
    Example: MCCOLXT1C0104  

  - `_embedded.payments.issuer` (object)
    An object containing information returned by the issuer.

  - `_embedded.payments.issuer.authorizationCode` (string, required)
    A code returned by the card issuer for a successful authorization. Used in reconciliation and dispute management.
    Example: T31306

  - `_embedded.payments.token` (object)
    If a token was created as part of your payment authorization request, the details are included in this object. This is currently available for [modular integrations](/products/modular/) only.

  - `_embedded.payments.token.href` (string)
    An `https` address for an Access Worldpay Token.
    Example: https://try.access.worldpay.com/tokens/eyJrIjoxLCJkIjoialRBL0FFelBzcnZpNCtzRGNRemh0NzI0NE1rdUtjMUFJdjYxVnlibWZuUT0ifQ

  - `_embedded.payments.token.tokenId` (string)
    Worldpay's internal identifier for a token.
    Example: 9897039852081922819

  - `_embedded.payments.paymentInstrument` (object)
    An object that contains information about the payment type.

  - `_embedded.payments.paymentInstrument.type` (string)
    The type of payment instrument used for this payment.
    Enum: "card/plain", "card/token", "card/checkout", "card/wallet+applepay", "card/wallet+googlepay", "card/networkToken", "card/networkToken+applepay", "card/networkToken+googlepay", "card/network", "card/plain+masked", "card/network+masked"

  - `_embedded.payments.paymentInstrument.card` (object)
    An object that contains information about the card used.

  - `_embedded.payments.paymentInstrument.card.number` (object)
    An object that contains information about the card number.

  - `_embedded.payments.paymentInstrument.card.number.cardBin` (string)
    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) (e.g. Visa, Cartes Bancaires), and the country. Card BINs are used to route transactions, check card capabilities, and in fraud assessments.
    Example: 444433

  - `_embedded.payments.paymentInstrument.card.number.last4Digits` (string)
    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

  - `_embedded.payments.paymentInstrument.card.number.fpanLastFour` (string)
    The last four digits of the actual card, where this was submitted in an authorization request that used a network token or a [mobile wallet](/products/wallets#submitting-card-metadata-to-worldpay) (encrypted or decrypted) `paymentInstrument`. Commonly referred to as the Funding Primary Account Number (FPAN).
    Example: 1111

  - `_embedded.payments.paymentInstrument.card.category` (string)
    Whether the card is classed as a consumer card or a card for commercial use.
    Enum: "commercial", "consumer"

  - `_embedded.payments.paymentInstrument.card.countryCode` (string)
    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

  - `_embedded.payments.paymentInstrument.card.expiryDate` (object)
    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`).

  - `_embedded.payments.paymentInstrument.card.expiryDate.month` (integer)

  - `_embedded.payments.paymentInstrument.card.expiryDate.year` (integer)

  - `_embedded.payments.paymentInstrument.card.issuerName` (string)
    The name of the card issuer.
    Example: AN ISSUING BANK LTD

  - `_embedded.payments.paymentInstrument.card.fundingType` (string)
    How the card is funded.
    Enum: "credit", "debit", "prepaid", "chargeCard", "deferredDebit"

  - `_embedded.payments.paymentInstrument.card.brand` (string)
    The card brand that the transaction was processed with. Sometimes referred to as the network or scheme.
    Example: visa

  - `_embedded.payments.paymentInstrument.card.paymentAccountReference` (string)
    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

  - `_embedded.payments.value` (object)
    An object that contains payment amount and currency.

  - `_embedded.payments.value.amount` (integer, required)
    This is a whole number including the currency exponent (e.g. GBP has an exponent of 2, so for £2.50 supply:`250`).

  - `_embedded.payments.value.currency` (string, required)
    The 3 digit currency code.

  - `_embedded.payments._links` (object)
    link to retrieveByPaymentId.

  - `_embedded.payments._links.self` (object, required)
    Self link to retrieveByPaymentId.

  - `_embedded.payments._links.self.href` (string)
    RetrieveByPaymentId provides event history and next action links.

## Response 400:

  - `400` (unknown)
    Bad request

## Response 400 fields (application/vnd.worldpay.payment-queries-v1.hal+json):

  - `errorName` (string, required)
    The type of error.
    Example: invalidPageSize

  - `message` (string, required)
    A description of the error.
    Example: Provided page size is not valid.

## Response 200 examples:

  - `Query payments within a specified date time range` (unknown)
    Query payments within a specified date time range

  - `Query payments within a specified date time range filtered by currency` (unknown)
    Query payments within a specified date time range filtered by currency

  - `Query payments within a specified date time range filtered by currency, amount` (unknown)
    Query payments within a specified date time range filtered by currency, amount

  - `Query payments within a specified date time range filtered by last4Digits` (unknown)
    Query payments within a specified date time range filtered by last4Digits

  - `Query payments within a specified date time range filtered by receivedEvents` (unknown)
    Query payments within a specified date time range filtered by receivedEvents

  - `Query payments within a specified date time range filtered by entityReferences` (unknown)
    Query payments within a specified date time range filtered by entityReferences

  - `Query payments by transactionReference` (unknown)
    Query payments using a transactionReference

  - `Query payments by transactionReference (with fpanLastFour & token info)` (unknown)
    Query payments using a transactionReference. We return the `fpanLastFour` for a mobile wallet payment.

  - `Query payments by transactionReference (no results)` (unknown)
    Querying a payment by a transactionReference, with no matching results found

  - `Query payments by orderReference` (unknown)
    Query payments using an orderReference

## Response 400 examples:

  - `Invalid parameter (pageSize)` (unknown)
    Invalid page size

  - `Invalid parameter (Start date too old)` (unknown)
    Start date must not be older than one year

  - `Invalid parameter (last4Digits)` (unknown)
    Exactly 4 integers must be provided