We constantly improve our products and add new functionalities on our platform. Usually these improvements and functionalities result in new product versions.
On this page, we describe the versioning of our APIs and server-side libraries.
APIs
When we introduce changes to our APIs, we follow best practices to have the least disruption on existing integrations. For example, for our REST APIs, we follow the API expand-contract pattern to add new elements without changing the version.
While we strive to reduce impact to existing integrations, we sometimes have to introduce changes that are not compatible with existing API versions. Doing so enables us to keep our APIs consistent and to improve the quality and developer experience.
When we introduce a breaking or incompatible change, we release a new API version to accommodate the change. The definition of a breaking change depends on the type of API.
Checking the API version
Most integrations use multiple Adyen APIs (see our API Explorer. Each API has a different version. Depending on how you are making the API calls, you can check the versions of the APIs that you are using from:
- Direct calls from your server: you can see the API version in the URLs that you use to reach the Adyen platform.
- Server-side libraries: when a server-side library version is released, the API version is included in the release notes. For example, see Adyen Java API library 17.2.0.
Each API URL contains a version suffix starting with either "v" or "V" character followed by a whole number to indicate the API version. We increment the number for every version, but we may skip numbers when needed.
Here are some examples of different API versions:
https://checkout-test.adyen.com/v68/payments // version 68
https://cal-test.adyen.com/cal/services/Account/v6/createAccountHolder // version 6
https://balanceplatform-api-test.adyen.com/bcl/v1/balanceAccounts // version 1To check if you are using the latest API version, refer to the version in our API Explorer.
New vs classic APIs
We categorize our APIs into two types: new or classic APIs. The type determines whether a change is compatible with an existing API version. For example, in new Adyen APIs, adding an optional field to a response body is a non-breaking change, while in classic APIs this change is considered breaking and therefore requires a new API version.
The following are classic APIs:
All other APIs that are not in the list above are new APIs, such as Checkout and Balance Platform.
Non-breaking changes
A non-breaking or backward-compatible change is an API change that allows your integration to continue using the API without any additional changes on your side. When we introduce new functionalities and changes to our APIs, we do our best to implement them in a backward-compatible way. We implement non-breaking changes in all versions of an API, so that you benefit from it without having to upgrade your API version.
We consider the following changes as non-breaking, depending on the API type.
| Non-breaking changes | New APIs | Classic APIs |
|---|---|---|
| Adding a new endpoint |  |
|
| Adding an optional field to a request body | |
|
| Adding any field to a response body | |
Breaking change |
| Adding an optional header to a request | |
|
| Adding a header to a response | |
|
| Changing the case of a header name | |
|
| Changing the value of a header | |
|
| Changing a field from required to optional in a request body | |
|
| Changing a field from optional to required in a response body | |
|
| Changing the text of an error message in a response | |
|
| Add a new HTTP status code for the response | |
|
| Deprecating a request or response field (for documentation) | |
|
Breaking changes
A breaking change is an API change that makes your current integration incompatible with the API. To avoid disrupting existing integrations, we introduce breaking changes in a new API version. You can continue to use existing API versions until you are ready to upgrade to the new version.
We consider the following changes as breaking, depending on the API type.
| Breaking change | New APIs | Classic APIs |
|---|---|---|
| Adding a required field to a request body | |
|
| Adding any field to a response body | Non-breaking change | |
| Adding a required header to a request | |
|
| Removing an existing endpoint | |
|
| Removing a field from a request body | |
|
| Removing a field from a response body | |
|
| Removing a header from a request | |
|
| Removing a header from a response | |
|
| Changing the HTTP status code of a response | |
|
| Changing error codes for an existing error | |
|
| Changing a field from optional to required in a request body | |
|
| Changing a field from required to optional in a response body | |
|
| Renaming a field in a request or response | |
|
| Changing the type of a field in a request or response | |
|
| Changing the behavior in a way that requires API consumers to change their integration for it to work properly. For example, if an API was ignoring some errors and now starts returning a validation error, the change is a breaking change. |
|
|
New API version without changes
In some cases, we may introduce a new API version without visible changes to API consumers. We do so to improve stability and consistency of our APIs, or to implement some groundwork for bigger changes in the future.
For the same reason, we sometimes skip numbers in a versioning of specific APIs.
Upgrading to a new API version
In general, we recommend upgrading to new API versions whenever possible. Keeping your integration up-to-date is crucial so you can take advantage of recent developments and improvements in our platform. However, if you decide stay in your current version, you can continue to do so. We maintain older versions of our APIs that you can continue to use until you are ready to upgrade.
To prepare for an API upgrade, refer to the release notes to find out about changes. For example, Checkout API.
Server-side libraries
Our server-side API libraries provide you with a convenient way to integrate without the need to directly connect to our APIs from your server-side code. Each library provides classes and methods that lets you use multiple Adyen APIs without needing to know the API versions. Instead, you need to consider the library version, which you specify when you include a library into your project.
Versioning
Adyen server-side API libraries use semantic versioning, which is based on the MAJOR.FEATURE.MINOR format:
- A MAJOR version release includes breaking changes to older usages of endpoints, such as changes in declarations and parameters.
- A FEATURE version release includes new, non-breaking features.
- A MINOR version release includes bug fixes or small non-breaking changes to endpoints.
Upgrading to a new version of a server-side library
We recommend that you upgrade to the latest version to benefit from new API releases and bug fixes. Check the latest releases from our GitHub repository.