API principles

This section gives an overview of the three specific standards that we are be following to create a market-leading API.

Hypermedia as the Engine of Application State (HATEOAS)

HATEOAS is the concept of application architecture. It defines the way clients’ applications talk with a server, through the use of the hyperlinks in your response body.

When you make a payment request, the response contains a _links object with all the next possible actions.

The example below shows the _links object returned when youquery the root resource. These links allow you to authorize a payment or create a token. When you send your request to either of these links, you get a response with the next available actions.

Hypertext Application Language (HAL)

HAL defines the format of the API's resources and links. It makes hyperlinking between API resources consistent and easy. It allows for the interlinking of our different APIs for a more consumable and explorable experience.

HAL is both machine and human readable. Which allows for context to be taken from the API Reference.

Media types

The media type specifies the nature and format of the JSON file. It defines how the file should be processed. The formatting of your request has to meet the standard or the request is not be accepted.

Our media type is defined in our Content-Type header and is standardized across our APIs.

Content-Type: application/vnd.worldpay.payments-v6+json


The version of our API you are using is defined in the media type. The example above shows that ourPayments APIis currently on version 6. We strive to update our APIs to provide you with the latest features. You can find any changes and release dates, whether breaking or non-breaking, at the bottom of the respective API documentation. To give you an example, the Versioning/ Change log for our Payments API liveshere.

Updating our APIs could mean that the previous schemas are no longer supported in the latest update. Our documentation is always reflecting the latest version of our APIs, but to find schemas for previous versions, see ourAPI reference.

You can find documentation for previous APIs in ourOlder Versionssection.

Why do you release new API versions?

To introduce new features in our APIs, which may introduce a breaking change.

Does a new API version always introduce a breaking change?

Generally yes, we may introduce a new parameter in a request that is not recognized in the previous version of the API.

Are the versions backward compatible?

No, each version may accept a different schema, we detail the schema for each version in ourAPI reference, as thedocumentationmostly reflect the latest version of our APIs.

Non-breaking change definition

To ensure resilience when integrating into any of our Access APIs, you must consider that Worldpay might make the following changes without moving to another version:

In Responses:

In Requests

Important: Sending any elements not recorded in our documentation will return an error.

Note: For any changes that fall outside the above definition, Worldpay creates a new version. Go to ourformatting pagefor current standards.

You should now familiarize yourself with our best practices oncertificate handling.