Skip to content
Baseline
APIs/
Payment Queries

Payment Queries (1)

Query your payments data based on a variety of parameters.

Authentication

Set your headers:

  Authorization: {your_credentials}
  Accept: application/vnd.worldpay.payment-queries-v1.hal+json

Replace {your_credentials} with your base64-encoded Basic Auth username and password.



DNS whitelisting

Whitelist the following URLs:

  • https://try.access.worldpay.com/
  • https://access.worldpay.com/

Please ensure you use DNS whitelisting, not explicit IP whitelisting.

Download OpenAPI description
openapi.json
openapi.yaml
Languages
Servers
Test (Try)
https://try.access.worldpay.com/
Live
https://access.worldpay.com/

Query payments

Request

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.

Security
BasicAuth
Query
startDatestringrequired

An ISO 8601 date-time supplied as a string. Filters for payments that occurred after the specified date-time. Must be supplied alongside endDate.

Example: startDate=2024-04-28T21:30:20Z
endDatestringrequired

An ISO 8601 date-time supplied as a string. Filters for payments that occurred below the specified date-time. Must be supplied alongside startDate.

Example: endDate=2024-05-31T21:30:20Z
pageSizeinteger<= 300 characters

The maximum number of payments to be returned in the response (max 300).

Example: pageSize=10
currencystring

The three digit currency code.

Example: currency=GBP
minAmountinteger

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

Example: minAmount=0
maxAmountinteger

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

Example: maxAmount=1000
last4Digitsstring

The last four digits of the card number.

Example: last4Digits=1111
entityReferencesstring

Your entity reference(s).

Example: entityReferences=entityReference1,entityReference2
receivedEventsstring

Name of the event.

Example: receivedEvents=authorizationRequested, authorizationSucceeded
transactionReferencestring

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.

Example: transactionReference=Memory265-13/08/1876
Headers
Acceptstringrequired
Example: application/vnd.worldpay.payment-queries-v1.hal+json
No request payload

Responses

Summary information of list of payments within a specified date range.

Bodyapplication/vnd.worldpay.payment-queries-v1.hal+json
_linksobjectrequired

links to the pages.

selfobjectrequired

Self link to the page.

nextobject

Next page link if the response contains more pages.

_embeddedobjectrequired
paymentsArray of objects

Array of payments within the date range.

Response
application/vnd.worldpay.payment-queries-v1.hal+json

Query payments within a specified date time range

{
  "_links": {
    "self": {
      "href": "/paymentQueries/payments?startDate=2025-07-05T21:30:20Z&endDate=2025-07-08T21:30:20Z&pageSize=10"
    }
  },
  "_embedded": {
    "payments": [
      {
        "timestamp": "2025-07-07T12:09:36.984Z",
        "paymentId": "pay4u_lHl2jobU5S1T2pWkq10",
        "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-07-07T12:05:01.134Z",
        "paymentId": "pay3f7oMDb3cCr2z-e_5L4vt0",
        "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": "UNKNOWN",
            "paymentAccountReference": "Q1HJZ28RKA1EBL470G9XYG90R5D3E",
            "category": "consumer"
          }
        },
        "value": {
          "currency": "GBP",
          "amount": 500
        },
        "_links": {
          "self": {
            "href": "/paymentQueries/payments/pay3f7oMDb3cCr2z-e_5L4vt0"
          }
        }
      },
      {
        "timestamp": "2025-07-07T11:07:38.731Z",
        "paymentId": "pay7Ge3tsYs4rrt-ieK2A3Pi0",
        "transactionReference": "adb83260-cf42-439f-bd71-4ccdbc01d020",
        "transactionType": "cardOnFile",
        "authorizationType": "authorization",
        "entity": "default",
        "paymentInstrument": {
          "type": "card/plain"
        },
        "value": {
          "currency": "GBP",
          "amount": 250
        },
        "_links": {
          "self": {
            "href": "/paymentQueries/payments/pay7Ge3tsYs4rrt-ieK2A3Pi0"
          }
        }
      },
      {
        "timestamp": "2025-07-07T10:22:19.844Z",
        "paymentId": "a71b92c5-da14-4043-8083-76e7b3d23680",
        "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": "UNKNOWN",
            "paymentAccountReference": "Q1HJZ28RKA1EBL470G9XYG90R5D3E",
            "category": "consumer"
          }
        },
        "value": {
          "currency": "GBP",
          "amount": 250
        },
        "_links": {
          "self": {
            "href": "/paymentQueries/payments/a71b92c5-da14-4043-8083-76e7b3d23680"
          }
        }
      },
      {
        "timestamp": "2025-07-07T10:21:28.717Z",
        "paymentId": "2a4d37cb-03b1-48c0-a588-dc1a00a83c5f",
        "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": "UNKNOWN",
            "paymentAccountReference": "Q1HJZ28RKA1EBL470G9XYG90R5D3E",
            "category": "consumer"
          }
        },
        "value": {
          "currency": "GBP",
          "amount": 250
        },
        "_links": {
          "self": {
            "href": "/paymentQueries/payments/2a4d37cb-03b1-48c0-a588-dc1a00a83c5f"
          }
        }
      },
      {
        "timestamp": "2025-07-07T10:21:12.755Z",
        "paymentId": "e638cfbd-5df9-40da-9996-938bb636e299",
        "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": "UNKNOWN",
            "paymentAccountReference": "Q1HJZ28RKA1EBL470G9XYG90R5D3E",
            "category": "consumer"
          }
        },
        "value": {
          "currency": "GBP",
          "amount": 250
        },
        "_links": {
          "self": {
            "href": "/paymentQueries/payments/e638cfbd-5df9-40da-9996-938bb636e299"
          }
        }
      }
    ]
  }
}

Retrieve a payment

Request

Retrieve a single payment by payment ID.

The API returns detailed data for payments processed after 25 June 2024. For payments processed before then use our query for historical payments.

Security
BasicAuth
Path
paymentIdstringrequired

Unique identifier generated for each payment. Historic paymentId values in UUID format.

Example: payv0A4Hx2eY1-5P2_CpV7qy0
Headers
Acceptstringrequired
Example: application/vnd.worldpay.payment-queries-v1.hal+json
No request payload

Responses

Retrieve complete details of a single payment including the event history & next action links.

Bodyapplication/vnd.worldpay.payment-queries-v1.hal+json
timestampstring

Payment initial authorization time.

Example: "2024-05-30T09:49:45.962Z"
paymentIdstring[ 25 .. 36 ] characters^[A-Za-z0-9_-]*$

Unique identifier generated by us for a single payment. Generated at authorization, and maintained through successive payment actions.

Example: "pay4u_lHl2jobU5S1T2pWkq10"
transactionReferencestring[ 1 .. 64 ] characters^[-A-Za-z0-9_!@#$%()*=.:;?\[\]{}~`/+]*$

A unique reference generated by you, used to identify a payment throughout its lifecycle.

narrativeobject

The text that appears on your customer's statement. Used to identify the merchant.

line1stringrequired

The first line of the narrative which appears on your customer's statement (24 characters max. If character is not supported it is replaced with a space).

line2string

Additional details about the payment e.g. order number, telephone number.

transactionTypestring

The transaction type of the payment.

Enum"oneTime""cardOnFile""recurring"
authorizationTypestring

The authorization type of the payment.

Enum"authorization""sale"
entitystring[ 1 .. 32 ] characters^([A-Za-z0-9]+[A-Za-z0-9 ]*)?$

Merchant entity name.

Example: "default"
lastEventstring

The last event received for the payment

Enum ValueDescription
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.

Example: "authorizationSucceeded"
schemeobject

An object containing information returned by the card scheme.

referencestringrequired

The reference returned by the scheme for this particular payment authorization.

Example: "MCCOLXT1C0104 "
issuerobject

An object containing information returned by the issuer.

authorizationCodestring^[a-zA-Z0-9]+$required

A code returned by the card issuer for a successful authorization. Used in reconciliation and dispute management.

Example: "T31306"
paymentInstrumentobject

The payment instrument supplied in the authorization request.

typestring

The type of payment instrument supplied in the authorization request.

Enum"card/plain""card/network""card/networkToken""card/networkToken+applepay""card/networkToken+googlepay""card/plain+masked"
cardobject

An object that contains information about the card used.

updatedPaymentInstrumentobject

The payment instrument supplied in the authorization request.

typestring

The type of payment instrument supplied in the authorization request.

Enum"card/networkToken""card/plain+masked"
cardobject

An object that contains information about the card used.

accountUpdaterMessagestring

Details on the type of payment instrument update.

Enum ValueDescription
The merchant is not registered in the update program

Returned for Real Time Account Updater only. Contact Worldpay to enroll in the service.

The account number was changed

A new card has been issued with a change in the card number.

The account was closed

The account is closed and the card is no longer valid. Ask your customer for an alternative payment method.

The expiry was changed

A new card has been issued with an updated expiry date. In most cases the card number remains unchanged.

The issuing bank does not participate in the update program

Returned for Real Time Account Updater only. It is not known whether an account update is available.

Contact the cardholder for updated information

A match was found but you may need to contact the cardholder for updated card details. This could be due to cardholder opt-out or other reasons.

No match found

The BIN range is enrolled for account updates, but no match was found for the card account. One reason for this may be that the card issuer has recently changed.

No changes found

No changes to the card account were found.

valueobject

An object that contains payment amount and currency.

amountintegerrequired

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

currencystringrequired

The 3 digit currency code.

eventsArray of objects

An array that contains the history of events of a payment.

eventNamestringrequired

Worldpay has received your authorization request.

Value"authorizationRequested"
Discriminator
timestampstring

The ISO 8601 date-time at which the event was created.

commandIdstring[ 25 .. 36 ] characters^[A-Za-z0-9_-]*$

Unique identifier generated by us for a single instance of an interaction (command) with the Worldpay API.

Example: "cmdRvD-OxCyXgJLQ9_jbqXAC0"
_linksobject

Self link and next action links.

selfobjectrequired

Self link to the page.

payments:cancelobject

Next action links.

payments:eventsobject

Next action links.

payments:settleobject

Next action links.

payments:partialSettleobject

Next action links.

Response
application/vnd.worldpay.payment-queries-v1.hal+json

Retrieve a single payment using the paymentId where the requested authorization succeeded

{
  "timestamp": "2025-06-08T16:11:13.164Z",
  "paymentId": "payVGX28GOT7iDY5qanttPWF0",
  "transactionReference": "89197aeb-c94a-456e-8014-1272fbcb64eb",
  "narrative": {
    "line1": "trading name",
    "line2": "order number"
  },
  "transactionType": "oneTime",
  "authorizationType": "authorization",
  "entity": "default",
  "lastEvent": "authorizationSucceeded",
  "issuer": {
    "authorizationCode": "T31306"
  },
  "scheme": {
    "reference": "MCCOLXT1C0104  "
  },
  "paymentInstrument": {
    "type": "card/plain+masked",
    "card": {
      "number": {
        "last4Digits": "1111",
        "cardBin": "444433"
      },
      "brand": "visa",
      "expiryDate": {
        "month": 5,
        "year": 2030
      },
      "countryCode": "GB",
      "fundingType": "credit",
      "issuerName": "AN ISSUING BANK LTD",
      "paymentAccountReference": "Q1HJZ28RKA1EBL470G9XYG90R5D3E",
      "category": "consumer"
    }
  },
  "value": {
    "currency": "GBP",
    "amount": 1200
  },
  "events": [
    {
      "eventName": "authorizationRequested",
      "timestamp": "2025-06-08T16:11:13.164Z",
      "commandId": "cmd0-IiS92BsJR8VaJ10V_420"
    },
    {
      "eventName": "authorizationSucceeded",
      "timestamp": "2025-06-08T16:11:14.229Z",
      "outcome": "authorized",
      "commandId": "cmd0-IiS92BsJR8VaJ10V_420"
    }
  ],
  "_links": {
    "self": {
      "href": "/paymentQueries/payments/payv0A4Hx2eY1-5P2_CpV7qy0"
    },
    "cardPayments:cancel": {
      "href": "https://access.worldpay.com/payments/authorizations/cancellations/{linkData}"
    },
    "cardPayments:settle": {
      "href": "https://access.worldpay.com/payments/settlements/full/{linkData}"
    },
    "cardPayments:partialSettle": {
      "href": "https://access.worldpay.com/payments/settlements/partials/{linkData}"
    },
    "cardPayments:events": {
      "href": "https://access.worldpay.com/payments/events/{linkData}"
    },
    "cardPayments:partialCancel": {
      "href": "https://access.worldpay.com/payments/authorizations/cancellations/partials/{linkData}"
    },
    "cardPayments:reverse": {
      "href": "https://access.worldpay.com/payments/authorizations/reversals/{linkData}"
    }
  }
}

Query historical payments

Request

Query payments processed before 25 June 2024.

Provide a transactionReference and entityReference for a payment to find the matching payment in the archive.

Security
BasicAuth
Query
transactionReferencestringrequired

A unique reference generated by you, used to identify a payment throughout its lifecycle.

Example: transactionReference=89197aeb-c94a-456e-8014-1272fbcb64eb
entityReferencestringrequired

A merchant entity.

Example: entityReference=default
Headers
Acceptstringrequired
Example: application/vnd.worldpay.payment-queries-v1.hal+json
No request payload

Responses

Summary information of a payment.

Bodyapplication/vnd.worldpay.payment-queries-v1.hal+json
_linksobjectrequired

Self link and next action links.The Next action links are dependent on the lastEvent, refer to 'query for historical payments Response' section for more details.

selfobjectrequired

Self link to the page.

payments:cancelobject

Next action links.

payments:settleobject

Next action links.

payments:partialSettleobject

Next action links.

_embeddedobjectrequired
paymentsArray of objects

Array of payments.

Response
application/vnd.worldpay.payment-queries-v1.hal+json

Query historical payments with a transactionReference & entityReference

{
  "_embedded": {
    "payments": [
      {
        "lastEvent": "Authorized",
        "value": {
          "amount": 500,
          "currency": "GBP"
        },
        "paymentInstrument": {
          "type": "card/plain",
          "card": {
            "number": {
              "last4Digits": "1111"
            },
            "brand": "visa"
          }
        },
        "_links": {
          "payments:cancel": {
            "href": "https://try.access.worldpay.com/payments/authorizations/cancellations/eyJrIjoiazNhYjYzMiIsImxpbmtWZXJzaW9uIjoiNS4wLjAifQ==.sN:g8wd64bwkbrp0md+bPxcanBnk2zLdsIqSa1pR99GeDrCwEtsymFb5gQw9WlrStDTK3eIWPy93y:7njc4649JSrU7+vFDl1J36+cwOkX0lW4Z+fnZKMutoUGX3m1:miQ42Na870582T9ERg+1ZUryhkE+qW88hu1DdDl2T76sf:VXab5cMYWO6LS0UzlfoW8PkXm9A8Gx:X:2vAwKFXFzKnt23AOHd1MAcGi2rYDmNWql5dV+zBj9zyT7GZXrLmjasoJJfxtEasqXGr:dzHa6q9jMukzvEX+SLmppl6itAGDMxqvmBKsIqEipLj126"
          },
          "payments:settle": {
            "href": "https://try.access.worldpay.com/payments/settlements/full/eyJrIjoiazNhYjYzMiIsImxpbmtWZXJzaW9uIjoiNS4wLjAifQ==.sN:g8wd64bwkbrp0md+bPxcanBnk2zLdsIqSa1pR99GeDrCwEtsymFb5gQw9WlrStDTK3eIWPy93y:7njc4649JSrU7+vFDl1J36+cwOkX0lW4Z+fnZKMutoUGX3m1:miQ42Na870582T9ERg+1ZUryhkE+qW88hu1DdDl2T76sf:VXab5cMYWO6LS0UzlfoW8PkXm9A8Gx:X:2vAwKFXFzKnt23AOHd1MAcGi2rYDmNWql5dV+zBj9zyT7GZXrLmjasoJJfxtEasqXGr:dzHa6q9jMukzvEX+SLmppl6itAGDMxqvmBKsIqEipLj126"
          },
          "payments:partialSettle": {
            "href": "https://try.access.worldpay.com/payments/settlements/partials/eyJrIjoiazNhYjYzMiIsImxpbmtWZXJzaW9uIjoiNS4wLjAifQ==.sN:g8wd64bwkbrp0md+bPxcanBnk2zLdsIqSa1pR99GeDrCwEtsymFb5gQw9WlrStDTK3eIWPy93y:7njc4649JSrU7+vFDl1J36+cwOkX0lW4Z+fnZKMutoUGX3m1:miQ42Na870582T9ERg+1ZUryhkE+qW88hu1DdDl2T76sf:VXab5cMYWO6LS0UzlfoW8PkXm9A8Gx:X:2vAwKFXFzKnt23AOHd1MAcGi2rYDmNWql5dV+zBj9zyT7GZXrLmjasoJJfxtEasqXGr:dzHa6q9jMukzvEX+SLmppl6itAGDMxqvmBKsIqEipLj126"
          }
        }
      }
    ]
  },
  "_links": {
    "self": {
      "href": "/paymentQueries/archivedPayments?entityReference=default&transactionReference=Test123"
    }
  }
}