1. Backward-compatible API changes

Mambu Payments maintains backward compatibility for all API endpoints when possible. The following changes are considered backward-compatible and can be introduced without notice:

A new attribute being added
Existing attributes being reordered
A new enum value being added to an existing attribute

You should build your integration to:

Be tolerant of unknown fields
Not depend on the order of attributes
Accept new enum values

2. API versioning

Mambu Payments uses versioning to introduce breaking changes without impacting live customers. Breaking changes include changes such as:

An attribute being renamed
An attribute being removed
An attribute format being changed
A new logic being implemented for an existing feature

API versions are numbered using their release date (e.g., 2023-04-12). API versions are maintained for a minimum of 12 months after a new API version is released.

New customers and new API keys for existing customers are linked to the latest API version. Existing customers and API keys are automatically migrated to the latest API version 90 days after it has been released.

New features and improvements to existing features are only available in the latest API version.

The public documentation refers to the latest API version.

3. API versions

Version	Changelog	Default version date after
`2023-04-12`	Changelog API version 2023-04-12	May 24, 2023

4. Setting the API version

To use a specific version of the API, use the Numeral-Api-Version HTTP header of your API requests as follows:

curl --request GET \
     --url 'https://sandbox.numeral.io/v1/payment_orders?limit=25' \
     --header 'accept: application/json' \
     --header 'x-api-key: 279413050bb4455e9ae4dfb0bdf210fd' \
     --header 'numeral-api-version: 2023-04-12'

What's next

What's next