API upgrade

The Wajub API is date-versioned. Breaking changes are rare and always announced in advance. Here's the process for a smooth transition.

API versioning

The Wajub API uses date-based versioning via the X-Wajub-Version HTTP header:

curl https://api.wajub.com/payments \
-H "Authorization: pk_test.xxxxxxxx" \
-H "X-Wajub-Version: 2026-08-01"

Without the X-Wajub-Version header, the API uses the latest stable version. You can freeze a date to lock your integration.

Deprecation timeline

Upgrade steps

1. Read the new version's migration guide

Each new API version comes with a guide listing breaking changes. Consult it on the changelog.

2. Identify affected calls

# Search all Wajub URLs in your code
rg "wajub\.com" --type js --type ts --type py --type php

# Identify calls with a frozen version
rg "Wajub-Version" --type js   # Search for the version header

3. Update your calls in sandbox

Test the new version only with test keys, pinning it via the header:

curl https://api.wajub.com/payments \
-H "Authorization: sk_test.xxxx" \
-H "X-Wajub-Version: 2026-08-01"

4. Validate scenarios

Run through all your test scenarios with the new version:

• Payment initialization
• Success / failure / refund
• Webhooks (payload format, new fields)
• Transfers
• Pagination and filters

5. Deploy with toggle

As with a provider migration, use a progressive roll-out — drive the header value from an environment variable so you can roll forward or back without a deploy:

const apiVersion = process.env.WAJUB_API_VERSION || '2026-08-01';

const res = await fetch('https://api.wajub.com/payments', {
headers: {
  Authorization: process.env.WAJUB_PUBLIC_KEY,
  'X-Wajub-Version': apiVersion,
},
});

6. Clean up

Once the new version is stable in production, remove compatibility code and references to the old version.

Versioning best practices

• Don't freeze the version without reason: using the API without the X-Wajub-Version header gives you the latest stable version automatically, without manual updates.
• If you freeze, plan a toggle mechanism: environment variable or feature flag.
• Automate API tests: integration tests that hit the sandbox detect regressions as soon as a new version is available.
• Follow the changelog: subscribe to changelog notifications so you don't miss anything.

Example of typical changes between versions