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. You can force a specific version of the API by setting it in your API requests.

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

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'