Payments API versioning

The Payments API v3 is the latest iteration of TrueLayer's payments interface. Although we regularly make updates and improvements to the API, version 3 is a big milestone in the lifecycle of our product. We don't expect to introduce a 4th version of the payments API.

📘

We don't currently make breaking changes to the Payments API

When we introduce a compatible non-breaking change, we do not introduce a new version.

Non-breaking changes

We consider the following types of change to be non-breaking:

• Adding a new endpoint
• Adding a new field to a request body
• Adding a new field to a response body
• Changing a request body field to be optional from required, without a behavioural change
• Changing a response body field to required from optional
• Adding a request or response header entry
• Changing a request header entry from required to optional
• Changing a response header entry from optional to required
• Changing the value of a header
• Changing a response error message
• Adding a new response status code to existing ones

Breaking changes

We consider the following types of change to be breaking:

• Adding a required field to a request body
• Renaming a field in a request body
• Removing a field from a request body
• Removing a field from a response body
• Changing a required field in a response body to optional
• Removing a request header
• Removing a required response header
• Adding a required request header
• Changing a response header from required to optional
• Changing the type of a field in a request or response body
• Changing the behaviour of the API in a way that requires integration changes

The future of versioning for Payments

Currently, we thoroughly consider updates so we don't introduce breaking changes to the Payments API v3.

However, we would like to sometimes iterate on our API with small but breaking changes which improve its usage or add new features. We would achieve that by introducing minor versioning.