An ISO 8601 date-time supplied as a string. Filters for payments that occurred after the specified date-time. Must be supplied alongside endDate.
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.
https://try.access.worldpay.com/
https://access.worldpay.com/
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.
An ISO 8601 date-time supplied as a string. Filters for payments that occurred below the specified date-time. Must be supplied alongside startDate.
The maximum number of payments to be returned in the response (max 300).
This is a whole number including the currency exponent (e.g. GBP has an exponent of 2, so for £2.50 supply:250
).
This is a whole number including the currency exponent (e.g. GBP has an exponent of 2, so for £2.50 supply:250
).
Your entity reference(s).
Name of the event.
- testing (try)
https://try.access.worldpay.com/paymentQueries/payments
- live
https://access.worldpay.com/paymentQueries/payments
- Payload
- curl
- Python
- Java
- Node.js
- Go
- PHP
- Ruby
- C#
No request payload
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", "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", "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", "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", "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", "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", "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" } } } ] } }
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.
- testing (try)
https://try.access.worldpay.com/paymentQueries/payments/{paymentId}
- live
https://access.worldpay.com/paymentQueries/payments/{paymentId}
- Payload
- curl
- Python
- Java
- Node.js
- Go
- PHP
- Ruby
- C#
No request payload
Retrieve complete details of a single payment including the event history & next action links.
A unique reference generated by you, used to identify a payment throughout its lifecycle.
The text that appears on your customer's statement. Used to identify the merchant.
Merchant entity name.
An object containing information returned by the card scheme.
An object containing information returned by the issuer.
The payment instrument supplied in the authorization request.
The payment instrument supplied in the authorization request.
The type of payment instrument supplied in the authorization request.
Details on the type of payment instrument update.
Enum Value | Description |
---|---|
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. |
An object that contains payment amount and currency.
An array that contains the history of events of a payment.
Worldpay has received your authorization request.
- authorizationRequested
- authorizationSucceeded
- authorizationRefused
- authorizationFailed
- authorizationTimedOut
- saleRequested
- saleSucceeded
- saleRefused
- saleFailed
- saleTimedOut
- settlementRequested
- settlementRequestSubmitted
- settlementFailed
- settlementTimedOut
- refundRequested
- refundRequestSubmitted
- refundFailed
- refundTimedOut
- cancellationRequested
- cancellationRequestSubmitted
- cancellationFailed
- cancellationTimedOut
- reversalRequested
- reversalRequestSubmitted
- reversalFailed
- reversalTimedOut
Retrieve a single payment using the paymentId where the requested authorization succeeded
{ "timestamp": "2025-06-08T16:11:13.164Z", "transactionReference": "89197aeb-c94a-456e-8014-1272fbcb64eb", "narrative": { "line1": "trading name", "line2": "order number" }, "transactionType": "oneTime", "authorizationType": "authorization", "entity": "default", "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" }, { "eventName": "authorizationSucceeded", "timestamp": "2025-06-08T16:11:14.229Z", "outcome": "authorized" } ], "_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}" } } }
- testing (try)
https://try.access.worldpay.com/paymentQueries/archivedPayments
- live
https://access.worldpay.com/paymentQueries/archivedPayments
- Payload
- curl
- Python
- Java
- Node.js
- Go
- PHP
- Ruby
- C#
No request payload
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" } } }