Versioning

Your integration is pinned to an API version and keeps working as it is, whatever we change later. When we change the API in a way that could break your code, it is a new version, and you move to it when you choose. This is Stripe’s model, with the header PSP-Version where Stripe has Stripe-Version.

The current version is 2026-10-25.acacia; the top bar of these pages always shows it.

A version’s name

A version is a date and a release name, such as 2026-10-01.acacia:

• A new name (acacia, then basil) starts with changes that can break an integration: a field removed or renamed, a type changed, a parameter made required, a status that means something else. At most two a year.
• A new date under the same name (2026-10-01.acacia, then 2026-11-12.acacia) adds things only. Moving between them never needs a code change.

What we add without a new version, in every version at once: an optional parameter, a field in a response, an event type, a value of a status or an error code, a payment method. Write your code to ignore a field it does not know and to handle a value it does not know.

Choosing the version of a request

Send the version in the PSP-Version header:

A request pinned to a version

curl https://api.63-180-91-99.sslip.io/payments/pay_in_01J9… \
  -H "Authorization: Bearer sk_live_in_…" \
  -H "PSP-Version: 2026-10-25.acacia"

Your request	The version it runs in
PSP-Version names a version	That version
PSP-Version names no version we have, or is sent twice	None: 400 with the code invalid_api_version, and nothing runs
No PSP-Version, and your account has a default	Your account’s default
No PSP-Version, on your account’s first request	The current version, which becomes your account’s default

Your account’s first request sets its default to the current version, whether or not it sends PSP-Version, as Stripe does. A version is matched exactly as written: no spaces, lower-case name.

Every response the API runs your request for carries the version it was answered in, in its own PSP-Version header. A request refused before that, for its key, its address or its version, runs in no version, and its answer has no PSP-Version. Test and live keys share the account’s default, so try a new version with the header on a few requests first, in test mode.

Upgrading

1. Read the Changelog for every version between yours and the new one.
2. Send the new version in PSP-Version from your test integration, and fix what breaks.
3. Send it from your live integration. Once every request names it, the account’s default no longer matters to you.

Sending PSP-Version on every request is the safest way: your code then says which version it was written for, and a change of the account’s default cannot reach it.

Webhooks

A webhook endpoint can have a version of its own, given when it is created or changed later in the merchant portal (until its Webhooks page opens, by your account manager); one without a version follows your account’s default. Its events are shaped in that version, retries included.