Why the API is versioned

Versioning lets us improve the API without breaking your integration. When a change would
require you to update your code, we release it as a new version. Your integration keeps working
on the version it uses until you decide to move.

Version names

Each version is named YYYY-MM.<name>, for example 2026-08.knut. The date shows when the
version was released.

A new version is only released for changes that are not backward compatible, such as a
removed or renamed endpoint or field. Backward compatible changes, such as new endpoints, new
optional parameters or new fields in a response, are added to existing versions without a new
name. Build your integration to ignore response fields it does not recognise, so these additions
never affect you.

The default version

One version is the default. It is the current stable version and the one we recommend. A
request that does not choose a version is handled by the default version, so if you never choose
a version, your integration uses the default.

Version labels

Each version has its own API reference. Use the version selector at the top of this
documentation to see the endpoints and fields of a specific version. Versions are labelled as
follows:

Label	Meaning
Default	The default version. Stable and recommended.
Beta	Newer than the default. Available to try, but may still change before it becomes the default.
Deprecated	Older than the default. Still available, but plan to move to the default version.

Choosing a version

You can choose a version in two ways. If both are used, the header wins.

Per request: the `pensopay-version` header

Send the version name in the pensopay-version header:

GET /v2/payments HTTP/1.1
Host: api.pensopay.com
Authorization: Bearer <token>
pensopay-version: 2026-09.marius

This is the easiest way to try a new version on a few requests before you switch everything.

Write the version name exactly as it is listed. A request with a version name the API does not
know is rejected with 400 Bad Request.

Per API token: pin a version

In the pensopay app you can pin a version to an API token. Every
request made with that token then uses the pinned version, unless the request sends the
pensopay-version header.

Pinning is useful when you are ready to move your whole integration to a new version, without
changing the code that sends requests.

Beta versions

A new version is released as a beta before it becomes the default. A beta version may still
change before it is final, so only choose it on purpose, with the header or a token pin, and
check its API reference for changes before you rely on it.

When a version is retired

When a retirement date is set for a version, its responses include two headers:

Header	Meaning
`Deprecation`	The time the version was deprecated, as `@` followed by a Unix timestamp.
`Sunset`	The date and time after which the version is no longer available.

If you see these headers, plan your move to a newer version before the Sunset date.

Moving to a new version

Read the API reference for the new version and compare it with the version you use today.
Test your integration against the new version by sending the pensopay-version header,
for example in test mode.
When everything works, pin the new version to your API token, or send the header on every
request.