Retrieve a payment

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

Servers

testing (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.

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

pageSizestring

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=100

last4Digitsstring

The last four digits of the card number.

Example: last4Digits=1111

entityReferencesstring

Merchant entity names.

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=2024-04-28T21:30:20Z&endDate=2024-05-31T21:30:20Z&pageSize=5"
    },
    "next": {
      "href": "/paymentQueries/payments?startDate=2024-04-28T21:30:20Z&endDate=2024-05-30T09:49:31.410Z&paymentId=44809b32-6b71-4bd0-9b8c-ac29beb65059&pageSize=5"
    }
  },
  "_embedded": {
    "payments": [
      {
        "timestamp": "2024-05-30T19:44:19.836Z",
        "transactionReference": "Memory265-13/08/1876",
        "transactionType": "oneTime",
        "authorizationType": "authorization",
        "entity": "default",
        "paymentInstrument": {
          "type": "card/plain+masked",
          "card": { … }
        },
        "value": {
          "currency": "GBP",
          "amount": 250
        },
        "_links": {
          "self": { … }
        }
      },
      {
        "timestamp": "2024-05-30T09:50:17.051Z",
        "transactionReference": "Memory265-13/08/1876",
        "transactionType": "oneTime",
        "authorizationType": "authorization",
        "entity": "default",
        "paymentInstrument": {
          "type": "card/network"
        },
        "value": {
          "currency": "GBP",
          "amount": 250
        },
        "_links": {
          "self": { … }
        }
      },
      {
        "timestamp": "2024-05-30T09:49:49.843Z",
        "transactionReference": "7a5d0292-251f-48ed-a5c0-13c4c78d4487",
        "transactionType": "oneTime",
        "authorizationType": "authorization",
        "entity": "default",
        "paymentInstrument": {
          "type": "card/plain+masked",
          "card": { … }
        },
        "value": {
          "currency": "GBP",
          "amount": 250
        },
        "_links": {
          "self": { … }
        }
      },
      {
        "timestamp": "2024-05-30T09:49:45.962Z",
        "transactionReference": "89197aeb-c94a-456e-8014-1272fbcb64eb",
        "transactionType": "oneTime",
        "authorizationType": "authorization",
        "entity": "default",
        "paymentInstrument": {
          "type": "card/plain"
        },
        "value": {
          "currency": "GBP",
          "amount": 250
        },
        "_links": {
          "self": { … }
        }
      },
      {
        "timestamp": "2024-05-30T09:49:31.410Z",
        "transactionReference": "db0eea07-cd96-417f-8f78-90cc3908c81b",
        "transactionType": "oneTime",
        "authorizationType": "authorization",
        "entity": "default",
        "paymentInstrument": {
          "type": "card/plain+masked",
          "card": { … }
        },
        "value": {
          "currency": "GBP",
          "amount": 250
        },
        "_links": {
          "self": { … }
        }
      }
    ]
  }
}

Retrieve a payment

Request

Retrieve a 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.

Path

paymentIdstringrequired

Unique paymentId generated for each payment

Headers

Acceptstringrequired

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

No request payload

Responses

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

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

timestampstring

Payment initial authorization time.

transactionReferencestring

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

narrativeobject

An object that contains identification and further details of the merchant.

line1stringrequired

First line of text that appears on your customer's statement.

line2string

Second line of text that appears on your customer's statement.

transactionTypestring

An object that contains transaction type.

Enum"oneTime""cardOnFile""recurring"

authorizationTypestring

An object that contains authorization type.

Enum"authorization""sale"

entitystring

Merchant entity name.

paymentInstrumentobject

An object that contains information about the payment type.

typestring

An object that contains information about the payment type.

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.

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.

eventNamestring

Name of the event.

timestampstring

The time when the event is created.

outcomestring

Outcome of the event.

_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

Query payments within a specified date time range

{
  "_links": {
    "self": {
      "href": "/paymentQueries/payments?startDate=2024-04-28T21:30:20Z&endDate=2024-05-31T21:30:20Z&pageSize=5"
    },
    "next": {
      "href": "/paymentQueries/payments?startDate=2024-04-28T21:30:20Z&endDate=2024-05-30T09:49:31.410Z&paymentId=44809b32-6b71-4bd0-9b8c-ac29beb65059&pageSize=5"
    }
  },
  "_embedded": {
    "payments": [
      {
        "timestamp": "2024-05-30T19:44:19.836Z",
        "transactionReference": "Memory265-13/08/1876",
        "transactionType": "oneTime",
        "authorizationType": "authorization",
        "entity": "default",
        "paymentInstrument": {
          "type": "card/plain+masked",
          "card": { … }
        },
        "value": {
          "currency": "GBP",
          "amount": 250
        },
        "_links": {
          "self": { … }
        }
      },
      {
        "timestamp": "2024-05-30T09:50:17.051Z",
        "transactionReference": "Memory265-13/08/1876",
        "transactionType": "oneTime",
        "authorizationType": "authorization",
        "entity": "default",
        "paymentInstrument": {
          "type": "card/network"
        },
        "value": {
          "currency": "GBP",
          "amount": 250
        },
        "_links": {
          "self": { … }
        }
      },
      {
        "timestamp": "2024-05-30T09:49:49.843Z",
        "transactionReference": "7a5d0292-251f-48ed-a5c0-13c4c78d4487",
        "transactionType": "oneTime",
        "authorizationType": "authorization",
        "entity": "default",
        "paymentInstrument": {
          "type": "card/plain+masked",
          "card": { … }
        },
        "value": {
          "currency": "GBP",
          "amount": 250
        },
        "_links": {
          "self": { … }
        }
      },
      {
        "timestamp": "2024-05-30T09:49:45.962Z",
        "transactionReference": "89197aeb-c94a-456e-8014-1272fbcb64eb",
        "transactionType": "oneTime",
        "authorizationType": "authorization",
        "entity": "default",
        "paymentInstrument": {
          "type": "card/plain"
        },
        "value": {
          "currency": "GBP",
          "amount": 250
        },
        "_links": {
          "self": { … }
        }
      },
      {
        "timestamp": "2024-05-30T09:49:31.410Z",
        "transactionReference": "db0eea07-cd96-417f-8f78-90cc3908c81b",
        "transactionType": "oneTime",
        "authorizationType": "authorization",
        "entity": "default",
        "paymentInstrument": {
          "type": "card/plain+masked",
          "card": { … }
        },
        "value": {
          "currency": "GBP",
          "amount": 250
        },
        "_links": {
          "self": { … }
        }
      }
    ]
  }
}

Query historical payments

Request

Query payments processed before 25 June 2024.

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

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=testEntity

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 payments within a specified date time range

{
  "_links": {
    "self": {
      "href": "/paymentQueries/payments?startDate=2024-04-28T21:30:20Z&endDate=2024-05-31T21:30:20Z&pageSize=5"
    },
    "next": {
      "href": "/paymentQueries/payments?startDate=2024-04-28T21:30:20Z&endDate=2024-05-30T09:49:31.410Z&paymentId=44809b32-6b71-4bd0-9b8c-ac29beb65059&pageSize=5"
    }
  },
  "_embedded": {
    "payments": [
      {
        "timestamp": "2024-05-30T19:44:19.836Z",
        "transactionReference": "Memory265-13/08/1876",
        "transactionType": "oneTime",
        "authorizationType": "authorization",
        "entity": "default",
        "paymentInstrument": {
          "type": "card/plain+masked",
          "card": { … }
        },
        "value": {
          "currency": "GBP",
          "amount": 250
        },
        "_links": {
          "self": { … }
        }
      },
      {
        "timestamp": "2024-05-30T09:50:17.051Z",
        "transactionReference": "Memory265-13/08/1876",
        "transactionType": "oneTime",
        "authorizationType": "authorization",
        "entity": "default",
        "paymentInstrument": {
          "type": "card/network"
        },
        "value": {
          "currency": "GBP",
          "amount": 250
        },
        "_links": {
          "self": { … }
        }
      },
      {
        "timestamp": "2024-05-30T09:49:49.843Z",
        "transactionReference": "7a5d0292-251f-48ed-a5c0-13c4c78d4487",
        "transactionType": "oneTime",
        "authorizationType": "authorization",
        "entity": "default",
        "paymentInstrument": {
          "type": "card/plain+masked",
          "card": { … }
        },
        "value": {
          "currency": "GBP",
          "amount": 250
        },
        "_links": {
          "self": { … }
        }
      },
      {
        "timestamp": "2024-05-30T09:49:45.962Z",
        "transactionReference": "89197aeb-c94a-456e-8014-1272fbcb64eb",
        "transactionType": "oneTime",
        "authorizationType": "authorization",
        "entity": "default",
        "paymentInstrument": {
          "type": "card/plain"
        },
        "value": {
          "currency": "GBP",
          "amount": 250
        },
        "_links": {
          "self": { … }
        }
      },
      {
        "timestamp": "2024-05-30T09:49:31.410Z",
        "transactionReference": "db0eea07-cd96-417f-8f78-90cc3908c81b",
        "transactionType": "oneTime",
        "authorizationType": "authorization",
        "entity": "default",
        "paymentInstrument": {
          "type": "card/plain+masked",
          "card": { … }
        },
        "value": {
          "currency": "GBP",
          "amount": 250
        },
        "_links": {
          "self": { … }
        }
      }
    ]
  }
}

Payment Queries (1)

Query payments

Request

Responses

Do you like our page?

Retrieve a payment

Request

Responses

Do you like our page?

Query historical payments

Request

Responses

Do you like our page?