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.

    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.

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.

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:

Reordering elements

Elements within the response body can be sent in any order.

Example:

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

or

{
    "pear": "conference",
    "apple": "gala"
}
New elements A new element is now included in your response.

Example:

Before

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

After

{
    "apple": "gala",
    "pear": "conference",
    "melon": "honeydew"
}
New links and relationship types Additional action links and URI resources are now returned within your response.

Example:

Before

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

After

{
    "_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"
        }
    }
}
New enumerate errors

Additional errors may be added when new features warrant a new error condition. Additional validation errors may be added if new optional elements are added to the request.

New HTTP error codes

Additional HTTP error codes may be added when new features warrant a new error condition.

New headers

A new HTTP header is now added to our response.

In Requests

Important

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

Reordering elements

Elements within the request body can be sent in any order.

Example:

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

or

{
    "pear": "conference",
    "apple": "gala"
}
New optional elements

New elements that are not mandatory can now be sent. For example merchant.mcc in our Payments API or description in our Tokens API.

Example:

Before

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

After

{
    "apple": "gala",
    "pear": "conference",
    "melon": "honeydew"
}
Increase in element value size

The value of an element now allows for an increased number of characters.

Example:

Before

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

After

{
    "phrase": "the quick brown fox jumps over the lazy dog"
}
Increase in format/scope of an element value

Changes in validation rules mean that requests which previously resulted in an error may now not.

Example:

A "time" value which previously allowed only hours and minutes, now also optionally allows seconds.

Before

{
    "time": "11:50"
}

After

{
    "time": "11:50:59"
}
Increase in range values

We may expand the range of values we accept. This means requests that previously resulted in a validation error may now succeed.

For example, previously allowed range value was 10-50. New range is 10-100.

New enumerate values

Element value options have now increased.

Example:

Previously allowed value options are apple, pear and melon. You could now also submit mango.

Before

{
    "fruit": "apple"
}

After

{
    "fruit": "mango"
}
Note

For any changes that fall outside the above definition, Worldpay creates a new version. Go to our formatting page for current standards.

You should now familiarize yourself with our security best practices.