API Versioning

How Watenga versions its API, what counts as a breaking change, and how to upgrade safely.

How Watenga Versions Its API

A version is a date. The latest is 2026-10-29; the original is 2026-01-01. Every API app is pinned to one version: new apps to the latest (every existing app was moved to 2026-10-29 on 30 October 2026), and an app keeps its version until you change it. Changes that would break an integration ship only in a new version, so your integration keeps working exactly as it does today until you upgrade.

A request is answered in:

1. the version in its Watenga-Version header, when it sends one (an unknown version is refused with 400 INVALID_API_VERSION);
2. otherwise, the version the API app of the key is pinned to (2026-10-29 when it has none);
3. otherwise (dashboard sign-in, public pages), 2026-01-01.

Every response names the version it was answered in, in the Watenga-Version header. The official SDKs send the version they were built for on every request, so upgrading an SDK is how you upgrade its version.

What 2026-10-29 changed

For secret and restricted keys (publishable keys and the hosted pages keep their shapes):

• One casing. Every response key is snake_case (merchant_transaction_id, display_id, is_active). Your metadata keys come back exactly as you set them. Request bodies take snake_case everywhere (camelCase is still accepted).
• One list shape. { "object": "list", "data": [...], "has_more": true, "next_cursor": "..." }, with total_count where the list counts. Pass next_cursor back as cursor for the next page; the SDKs page for you (see Pagination).
• Objects, not wrappers. A refund answers the refund; a subscription answers the subscription (its invoice and payment URL beside it).
• Errors name fields in snake_case (error.param).

Webhook events have one envelope in every version; their api_version is your app's.

Deprecated routes

A route is never removed without warning. It is first deprecated: it keeps working, every response carries a Deprecation header (and a Link to its successor and to the changelog), the API reference marks it, and the changelog says what to use instead. A removal date is announced as a Sunset header at least six months ahead.

What Counts as a Breaking Change

Watenga considers the following to be breaking changes that require a new API version:

• Removing a field from a response — if you currently read transaction.cardLast4 and we removed that field, your code would break.
• Changing the type of a field — if feeAmount changed from a string to a number, strict type checks in your code would fail.
• Changing the meaning of a field — if status values changed from completed to succeeded, your if (status === 'completed') checks would stop working.
• Removing an endpoint — if we removed GET /v1/transactions/:id, any code calling it would break.

The following are not breaking changes and can happen at any time without a version bump:

• Adding a new field to a response — your code should ignore unknown fields.
• Adding a new endpoint — existing integrations are unaffected.
• Adding a new optional request parameter — omitting it still works.
• Fixing a bug — even if you were relying on the buggy behaviour, a security fix takes precedence.

Checking Your Current Version

Your API version is shown in the Developer Console under each API app. It is also returned in the Watenga-Version response header on every API call:

curl -I https://api.watenga.africa/v1/account/balance \
  -H "Authorization: Bearer sk_test_YOUR_KEY"

HTTP/2 200
content-type: application/json
watenga-version: 2026-10-29
...

Upgrading Your API Version

1. Read what changed in the changelog.
2. Try it per request first: send Watenga-Version: 2026-10-29 from your test integration (or upgrade the SDK, which sends it for you) and run your tests.
3. Change the app's version in the Developer Console → your API app → API version (dashboard sign-in; recorded in the audit log). Upgrade your test app before your live app. You can switch back the same way.

Migration Guides

Watenga gives at least six months' notice — in the changelog and as a Sunset header — before a version or a deprecated route stops working.