API Lifecycle

Our API has a single version that evolves over time instead of having multiple versions simultaneously. This allows us to introduce new features and improve functionality while maintaining a stable and reliable experience for our users. This section outlines how we manage changes to the API, including how we handle feature additions, deprecations, and communications.

Guiding Principles

Incremental Evolution: Instead of releasing entirely new versions of the API, we enhance the current version by adding new features and deprecating outdated ones.
Backward Compatibility: We strive to ensure that changes to the API do not break existing integrations.
Transparency: We are committed to keeping our users informed about API changes through clear and timely communication.

Understanding Breaking and Non-Breaking Changes

In the light of evolving our API, it’s critical to distinguish between breaking changes, which can disrupt existing integrations, and non-breaking changes, which enhance functionality without affecting current users.

Breaking Changes

Breaking changes alter the behavior of the API in a way that existing clients cannot function without modifications. These changes require users to update their integrations to maintain compatibility.

We consider the following types of changes to be breaking.

Removing or Renaming Endpoints

Removing an endpoint entirely.
Changing the URL structure (e.g., /merchants/{id} to /accounts/{id}).

Modifying Request or Response Formats

Adding required fields to requests.
Removing required fields from requests or responses.
Renaming or deleting response fields.
Renaming or deleting required query parameters.
Changing the data type of a field (e.g., integer to string).

Altering HTTP Methods

Changing the HTTP method for an operation (e.g., from GET to POST).

Modifying Authentication or Authorization Requirements

Introducing new mandatory authentication methods.
Changing access permissions for an existing endpoint.

Altering Error Codes

Removing or significantly changing error codes that clients rely on for handling errors.

Sometimes breaking changes are unavoidable. Read the next section on what our policy is around these types of changes.

Non-Breaking Changes

Non-breaking changes enhance the API in ways that do not require existing clients to update their integrations. These changes are backward-compatible and ensure that current workflows remain unaffected. You must be sure that your integration can handle these types of changes.

We consider the following types of changes to be non-breaking.

Adding New Endpoints

Introducing new endpoints that do not interfere with existing ones.

Adding Fields

Adding new optional fields to the request.
Adding new optional or required fields to the response.
Making previously required fields optional.

Change the Order

Changing the order of the JSON fields in the request or in the response.

Adding New Query Parameters

Adding new optional query parameters that are not required for existing functionality.

Adding New Error Codes

Introducing new error codes while retaining existing ones.

Improving Performance or Stability

Optimizing the backend to improve response times or reliability without altering the API’s contract.

Deprecation Policy

Occasionally, certain features may become obsolete and need to be deprecated. The removal of these features might mean your integration will break. That’s why we have a phased deprecation process in place, which follows these steps:

Announcement: Deprecations are announced in advance through our changelog and email notifications.
Deprecation Warnings: Deprecated features are marked with a tag that says DEPRECATED. Next to that, the removal date will also be specified.
Grace Period: We provide a sufficient grace period (typically 6 months) to allow clients to transition away from deprecated features.
Removal: Once the grace period ends, deprecated features are removed. If necessary, detailed migration guides are provided to assist users in adapting to alternatives.

Testing and Feedback

To ensure a smooth integration experience for our users we provide the following:

Beta Features: New features may be released as experimental for early testing and feedback. Features that are experimental are marked with the BETA tag.
Sandbox Environment: Users can test their integration in a dedicated sandbox environment without production impact. Our sandbox environment is duplication of the entire production system where we simulate responses from upstream systems (such as issuers).
Feedback Channels: We encourage users to share their feedback on proposed changes via our support team.

Commitment to Stability

Our goal is to ensure a seamless experience for our users as the API evolves. By following this policy, we aim to balance innovation with stability, enabling you to build and maintain robust integrations with confidence.

For questions or concerns about our API evolution policy, please contact our support team or visit our developer portal for more information.