API Principles

This section gives you an overview of the standards we are following to create a market-leading API.

API overview

• Hypertext Application Language (HAL) for learnability

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

  HAL is both machine and human readable; an advantage that means you can get context from API Reference.

  We follow this convention to structure our resource and action links so you can use them with standard libraries.

• Media Types to control API version usage

  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 must meet the standard or the request is not accepted.

  Our Media type is defined in our Content-Type header, it defines the API version and is standardized across our APIs.

  Copy

  Copied!

  Content-Type: application/vnd.worldpay.verifiedpayments-v1.hal+json

  Content-Type: application/vnd.worldpay.verifiedpayments-v1.hal+json

Best Practice

Access Worldpay returns a WP-CorrelationId in the headers of service responses. We highly recommend you log this. The WP-CorrelationId is used by us to examine individual service requests.

Versioning

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 Verified 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:

{
    "apple": "gala",
    "pear": "conference"
}

{
    "pear": "conference",
    "apple": "gala"
}

{
    "apple": "gala",
    "pear": "conference"
}

{
    "apple": "gala",
    "pear": "conference",
    "melon": "honeydew"
}

{
    "_links": {
        "service:action1": {
            "href": "https://access.worldpay.com/service/action1"
        },
        "service:action2": {
            "href": "https://access.worldpay.com/service/action2"
        }
    }
}

{
    "_links": {
        "service:action1": {
            "href": "https://access.worldpay.com/service/action1"
        },
        "service:action2": {
            "href": "https://access.worldpay.com/service/action2"
        },
        "service:action3": {
            "href": "https://access.worldpay.com/service/action3"
        }
    }
}

In Requests

{
    "apple": "gala",
    "pear": "conference"
}

{
    "pear": "conference",
    "apple": "gala"
}

{
    "apple": "gala",
    "pear": "conference"
}

{
    "apple": "gala",
    "pear": "conference",
    "melon": "honeydew"
}

{
    "phrase": "the quick brown fox"
}

{
    "phrase": "the quick brown fox jumps over the lazy dog"
}

{
    "time": "11:50"
}

{
    "time": "11:50:59"
}

{
    "fruit": "apple"
}

{
    "fruit": "mango"
}

You should now familiarize yourself with oursecurity best practices.