API upgrade
How your API version is chosen, and how to move to a newer one.
The API is versioned by date: your account is pinned to a version, and a request can ask for another
one with the X-Wajub-Version header. Versioning lists the supported versions; a
version outside that list answers 400.
A new field is not a new version
Fields added to a response, new endpoints and new enum values ship without a version bump. Parse responses so an unknown field is ignored rather than fatal, and treat an unfamiliar status as not-yet-final rather than crashing on it.
How your version is chosen
Three sources, first match wins.
- 1
The X-Wajub-Version header
Per request, and it overrides everything else. Must look exactly like
2026-09-01. - 2
The version pinned on your account
Set when the account was created, or by support. Applies to every call that does not carry the header.
- 3
The platform default
The current version, today
2026-10-11.
Whatever wins, the resolved version comes back on every response in the same header. That is the only reliable way to know which one you actually got.
curl https://api.wajub.com/transfers/po_kZ3qP8mWvL2xR7tB \
-H "Authorization: sk_test.xxxxxxxxxxxxxxxx…" \
-H "X-Wajub-Version: 2026-08-01" \
-D -A malformed header is ignored, not rejected
A header that does not match YYYY-MM-DD exactly, such as 2026-8-1 or v2, is ignored and
your account's version applies. Check the response header rather than assuming your request header
was honoured.
Moving up a version
- 1
Read what changed
The changelog lists what each version changes. Grep your code for the field names it names, in both directions.
- 2
Pin the new version in sandbox
Send the header with a test key and run your scenarios: initialisation, success, failure, refund, transfer, webhook handling, pagination.
- 3
Drive the header from configuration
An environment variable rather than a literal, so rolling back is a restart instead of a deploy.
- 4
Raise it in production
Watch the same signals as any other rollout, then remove the compatibility branches once it holds.
In the Node SDK, per-request headers go in the request options alongside idempotencyKey, which
is where the version header belongs while you are testing one.
Compare payloads rather than guessing
Konsole logs the resolved version next to the request body, so two calls on two versions can be read side by side in the log explorer.
Sunset policy
A version is announced as deprecated with six months of notice before it leaves the supported list,
and the changelog is where that is published. Once removed, calls pinned to
it get a 400 rather than a silent downgrade, which is deliberate: a silent downgrade
would change your payloads without telling you.