Access Worldpay
/
API Principles

API principles

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

API design approach

We follow industry-standard conventions so you can use familiar tools. Our APIs are designed to let you self-serve. They show you next steps, are learnable, and present with documentation and certification to support your integration.

How does it work?

  • Dynamic next action links to optimize your journey

    Our API services can optimize your next actions for your specific payment journey.

    We return dynamic next action links as hypermedia links to make the possible payment journey intuitive, learnable and to avoid you making mistakes.

    Note

    Our dynamic next action links are unique to the action type for individual transactions. The maximum length of the encrypted action link data excluding the base URL will be up to 1024 characters.

    The example below shows the _links object returned in the response of a card payment request. These links allow you to get the status of a payment or action a cancellation or settlement.

{
    "_links": {
        "cardPayments:cancel": {
            "href": "https://try.access.worldpay.com/payments/authorizations/cancellations/eyJrIjoiazNhYjYzMiI="
        },
        "cardPayments:settle": {
            "href": "https://try.access.worldpay.com/payments/settlements/full/eyJrIjoiazNhYjYzMiI="
        },
        "cardPayments:partialSettle": {
            "href": "https://try.access.worldpay.com/payments/settlements/partials/eyJrIjoiazNhYjYzMiI="
        },
        "cardPayments:events": {
            "href": "https://try.access.worldpay.com/payments/events/eyJrIjoiazNhYjYzMiI="
        },
        "curies": [
            {
                "name": "cardPayments",
                "href": "https://try.access.worldpay.com/rels/cardPayments/{rel}",
                "templated": true
    }
  }
}

  • Modular and composite resources to support different use cases

    Some of our action links are dynamic to guide through the optimum payment flow. Our APIs are designed to be a toolset that enables you to integrate them into your journeys so that you can optimize your payment patterns and outcomes. Additionally, some of our next action links are composite allowing you to perform multiple actions in one call.

  • Consistent language across different interaction journeys

    Focusing on making our APIs as easy to integrate and use, the language across different services is aiming to be same. This ensures learnabilty, usability and quick integration.

  • 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

    As part or our broader API versioning strategy (reviewed 2023), we are changing how we version our services to ease your integration. We are removing the versioning from the Content-Type. This is to standardize across our services and therefore reduce friction.

    We have added a new custom version HTTP header which uses a date based scheme rather than semantic versioning:

    WP-Api-Version: 2023-06-01

    Previous versioning in Content-Type header:

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

Discovery

To integrate our APIs you interact directly with their resource. This is reflected in the documentation for:

The documentation for older services describes an integration through discovery by querying the root resource. This is no longer necessary. Our service URIs are stable and a direct call simplifies the integration.

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:

Changing URIs/URIS and their FQDNs/paths

The structure and length of a URI/ URI including the Fully Qualified Domain Name (FQDN) and their path might change.

Example:

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

or

{
    "_links": {
        "service:action": {
            "href": "https://api.access.worldpay.com/api/process"
        },
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 object or new attributes within an object are now included in your response.

Example:

Before

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

After

{
    "apple": "gala",
    "pear": "conference",
    "melon": "honeydew"
}
New links & 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.