Versioning
Date-based versions, what has changed, and how to move to a new one.
The Wajub API is versioned by date. Your account is pinned to the version that was current when you created it, and a breaking change ships under a new date without touching your integration. The current version is 2026-10-11.
Supported versions
| Version | Status | What it changed |
|---|---|---|
2026-10-12 | New accounts | A channel of GET /channels and GET /providers no longer has currency, which read XAF for every channel. A payment link has no category_id: it is neither taken on POST and PUT /links, nor read by GET /links, nor returned. A transfer or a refund stopped before it was sent reads cancelled, no longer failed, and ?status=failed no longer lists it; once this version is current, webhooks announce it as transfer.cancelled or refund.cancelled, not transfer.failed or refund.failed. New accounts are pinned to it; an existing account keeps its version and reaches this one with the X-Wajub-Version header. Webhooks still follow the current version. |
2026-10-11 | Current | A payment's status reads refunded or partially_refunded once refunds have succeeded, and GET /payments?status= filters on that reading. |
2026-09-01 | Supported | ledger_balance_before and ledger_balance_after removed from the transfer object. |
2026-08-01 | Supported | complete replaces is_complete on the transfer object. |
2025-01-01 | Supported | The original version. |
A version stays supported for at least six months after it is superseded, and the removal is announced before it happens. An announced version is served to whoever asks for it with the header, so you can try it before it becomes current; no account is moved to it.
Choosing a version
Three sources are consulted, in this order: the X-Wajub-Version header on the request, the
version pinned on your account, then the platform default.
Authorization: sk.xxxxxxxxxxxxxxxx...
X-Wajub-Version: 2026-08-01The header only counts if it matches YYYY-MM-DD. Anything else, a v2, a latest, an empty
string, is ignored in silence and your account's version applies instead. A well-formed date that
is not on the supported list is a hard error:
From a browser, a page may send X-Wajub-Version with a public key: the preflight accepts it, and
the 400 above carries the CORS headers, so the page reads the message instead of a CORS failure.
Every response says which version answered
X-Wajub-Version comes back on every response, including errors and the 400 above, and a page's
code can read it. Log it: it
is the fastest way to find out that a service you forgot about is still pinned to an old date.
curl -i https://api.wajub.com/transfers/po_225KMKULRQqYvlhrgUOE \
-H "Authorization: $WAJUB_API_KEY" \
-H "X-Wajub-Version: 2026-08-01"Translation happens on both sides
Pinning an old version keeps that version's whole contract, in requests and in responses. A
client on 2025-01-01 sends and reads is_complete, and a transfer read on 2026-08-01 still
carries ledger_balance_before and ledger_balance_after, although those fields were removed in
2026-09-01.
What counts as breaking
Breaking, ships under a new datebreakingoptionalAdditive, ships immediatelyadditiveoptionalParse tolerantly
Additive changes reach every version, including yours, without notice. Ignore fields you do not
recognise, and never let an unknown enum value throw. A match with no default branch is the
single most common reason an integration breaks on a non-breaking release.
Moving to a new version
- 1
Read what changed
The changelog lists the diff for each date, field by field.
- 2
Test with the header
Send
X-Wajub-Versionwith the new date using a sandbox key. Nothing on your account changes, so you can run it alongside your current integration for as long as you need. - 3
Roll it out per service
Keep the header in place while you deploy, one service at a time. A service you have not migrated keeps answering on the old date.
- 4
Pin the account, drop the header
Once everything runs on the new date, ask support to move your account's pinned version, then remove the header. Konsole → Overview shows which version your account is pinned to and which one is current, so you can confirm the change landed.