API versioning and deprecation

The version is in the path: every public endpoint is under /v1 (https://api.xaalis.org/v1/…, test mode at https://sandbox-api.xaalis.org/v1/…). v1 is the only version today. The contract is the OpenAPI document the API publishes at https://api.xaalis.org/openapi.json.

Changes that can happen within v1

These are backward-compatible and ship without a new version or advance notice. Write your integration so they don’t break it:

• New endpoints, and new optional request parameters or headers.
• New fields in response objects and in webhook payloads — ignore fields you don’t know.
• New webhook event types — ignore types you don’t handle and still answer 2xx.
• New values in string enums (a new payment status, a new provider, a new error code) — treat an unknown value as “not one I handle”, never as an error that stops processing.
• New error codes, longer error messages, a different order of fields, IDs of a different length (keep the prefix: pay_, po_, …).

Changes that need a new version

Removing or renaming an endpoint, a field or an enum value; making an optional parameter required; changing a field’s type or meaning; changing how amounts are expressed (they stay integer XOF). These only ship as /v2, next to v1, never by changing v1 in place.

How a deprecation is announced

When something in v1 is deprecated:

1. It’s announced on this page and by e-mail to every account owner, with the date it stops working.
2. Responses from the deprecated endpoint carry the standard Deprecation header (RFC 9745) and a Sunset header with the end date (RFC 8594), plus a Link to the replacement.
3. It keeps working for at least 12 months after the announcement.

Nothing is deprecated today.

SDKs and plugins

The Node, Python and PHP SDKs and the WooCommerce plugin follow semantic versioning: a breaking change in an SDK’s own interface means a new major version, even when the API itself doesn’t change. See Downloads for the current versions.