Menu

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 modular APIs help you with your specific use cases. This combined is designed to optimize your payment flow. 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?

  • Present actions as Restful HTTP resources for easy integration into your journeys

    The initial step is to get our root resource to show you what’s available. We provide resources that you can perform standardized HTTP methods (POST, PUT, GET etc) against.

  • 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 when youquery the root resource. These links allow you to authorize a payment or create a token.

    Copied!
    {
  "_links": {
      "payments:authorize": {
      "href": "https://try.access.worldpay.com/payments/authorizations"
      },
      "tokens:tokens": {
      "href": "https://try.access.worldpay.com/tokens"
      }
  }
  }

  • 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

    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.

    Copied!
    Content-Type: application/vnd.worldpay.payments-v6+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

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.