API Versioning

📘

Note on Terminology

In this document, backward-incompatible changes and breaking changes mean the same thing. We use the terms interchangeably.

Use API versioning to adopt new features and improvements in our payment APIs without disrupting your existing integration. Each version of the Flutterwave For Business (F4B) API may introduce new functionality to enhance your payment workflows.

We release new versions to introduce backwards-incompatible changes without affecting your current setup. By versioning APIs, we let you plan, test, and adopt changes at your own pace.

When we release a new API version, we update the API changelog and announce it through our official channels. Versions older than 12 months are no longer actively supported and will not receive updates.

Specify the API version in your request header using X-API-Version. If you don’t provide a version, we default to the latest version available.

Our APIs follow semantic versioning that takes this format: MAJOR.MINOR.PATCH.

• MAJOR introduces breaking changes to existing endpoints.
• MINOR adds backwards-compatible features.
• PATCH includes non-breaking fixes or improvements.

Backwards-Incompatible Changes

A change is considered non-breaking if it allows your integration to continue working without requiring major updates. These include:

1. Adding new API endpoints.
2. Adding optional request parameters to existing API endpoints.
3. Adding new data fields to existing API or webhook responses.
4. Reordering data fields in existing API or webhook responses.
5. Changing a field from optional to required in API or webhook response.
6. Modifying the length or format of opaque strings e.g. object IDs, error messages, and other human-readable strings.
7. Adding new webhook event types.

A change is considered breaking if it requires updates to your existing implementation. These include:

1. Adding a required field to the request body.
2. Adding a required header to the request.
3. Removing required parameters from the request body.
4. Changing API and webhook structure for existing features.
5. Changing a field from optional to required in a request body.
6. Changing error codes for an existing error.

Upgrading to a New API version

Before upgrading, review the changelog to understand what’s changed. This helps you adjust your integration and take advantage of new features or events.

New API versions may impact:

1. The number and type of optional request parameters.
2. The structure and length of API responses or webhooks.
3. The format of Flutterwave-generated IDs in responses.