API upgrade
Dated versions, what changed in each, and how to pin one.
The API is versioned by date. Three versions are live at once, the newest is the default, and moving between them is a header change plus whatever the diff below asks of you.
| Version | Status |
|---|---|
2026-09-01 | Current, what you get by default |
2026-08-01 | Supported |
2025-01-01 | Supported |
Anything outside that list is refused outright.
What actually changed
Two breaking changes exist, both on transfers. Everything else has been additive, and additive changes do not get a version.
| Introduced | Change | What to do |
|---|---|---|
2026-08-01 | complete replaces is_complete on a transfer | Read complete |
2026-09-01 | ledger_balance_before and ledger_balance_after removed from a transfer | Drop them, they were internal ledger snapshots |
Older clients are not broken by either. Pin 2025-01-01 and a transfer still answers with
is_complete and both ledger fields, because the response is translated back down to your version
on the way out. Send is_complete on a newer version and it is translated up on the way in.
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-09-01.
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.kZ3qP8mWvL2xR7tB5nY4hC6dF9jS1aG0eU3i…" \
-H "X-Wajub-Version: 2026-08-01" \
-D -A malformed header is ignored, not rejected
The header is read only when it matches YYYY-MM-DD exactly. 2026-8-1, v2, or a value with
trailing whitespace is dropped silently and you fall through to your account pin or the platform
default. You get a 200 on a version you did not ask for. Check the response header rather than
assuming your request header was honoured.
Moving up a version
- 1
Read the diff
The table above is the whole set of breaking 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 the 400 above rather than a silent downgrade, which is deliberate: a silent downgrade
would change your payloads without telling you.