API versioning policy

📘

In this document, we use backward-incompatible changes and breaking changes interchangeably.

API versioning is a seamless way to incrementally improve your experience with our payment APIs. Different versions of F4B APIs would come with various additional features to enrich your payment experience.

Introducing new versions helps us add backward-incompatible features without breaking your existing code. By communicating early and providing sufficient resources, you can predict and implement these changes without breaking your application or user journey.

When we release a new API version, We'll update our API changelog and announce it through our official channels. Versions older than [X] months would not be actively supported and would not receive updates.

You can specify your preferred API version in your request's header as X-API-Version. When no version is specified in the request, We'll default to the latest API version available.

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

• Major version releases introduce breaking changes to the existing API endpoints.
• Minor updates add new non-breaking features like ABC.
• PATCH updates fix bugs or make small non-breaking changes to the endpoints

What are backward-incompatible changes

Flutterwave treats changes as backward-compatible (non-breaking) if they allow existing integrations to continue running with little or no additional dev work. Examples 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.

We also recognise the following as breaking API changes to your integration:

1. Adding a required field to the request body.
2. Adding a required header to the request.
3. Remove a required parameter 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 newer API version

When upgrading to a newer version, It is important to understand the changes documented in the changelog before making the switch. This would help you take full advantage of additional fields or events in your application flow.

New API versions could affect:

1. The number of optional parameters in your API requests.
2. The length and structure of your API response or webhook.
3. The values and format of Flutterwave generated IDs in your responses.