Versioning
Airwallex uses versioning to improve our API contracts without affecting existing users.
When we need to introduce a backwards-incompatible change, such as renaming or splitting a field, we will create a new date version which clients can migrate to when ready.
What is the latest version?
The latest version is 2026-07-17.
Which version am I using?
Your version is stored in your account and automatically applied to your API calls.
Please log in to view your version.
You may override this version on a per call basis by setting the x-api-version header. This should only be used in exceptional cases, such as when testing and migrating to a newer version, or when calling on behalf of another account.
How do I upgrade to a new version?
Refer to the Changelog to learn about the contract changes introduced in the new version. You can also view the full documentation for a selected version using the Version drop-down menu in the sidebar.
Testing and Development
Set the x-api-version header to the new version on the affected endpoints. Modify your code according to the new API contracts.
Test the changes in our sandbox environment without affecting live data. You may also use feature flagging to incrementally migrate traffic. For details, see Sandbox environment overview .
Switch to production
Once your production traffic is migrated to the new version via the x-api-version header, notify our support team. We will update your account to the new version. Shortly (> 1 hour) after this, you may remove the x-api-version header from your API calls.
How does Airwallex define "backwards-compatible" and "backwards-incompatible"?
The following are examples of backwards-compatible changes:
- Adding new API endpoints
- Adding new optional fields to request models
- Adding new fields to response models
- Adding new required fields to request models where the change relates to a new payment corridor or method
- Modifying content of unstructured text fields, such as error messages and field labels
We regularly introduce such backwards-compatible changes to our API to support new product features. These should not affect existing integrations so we can introduce them directly to all versions. This avoids clients having to upgrade to a newer version to utilise the new functionality. Please ensure your integration supports these changes, e.g. disable checks on unknown fields in the response.
Changes other than these may be either of the following:
- Backwards-incompatible change: these are changes to our API contracts which we can use versioning to avoid existing client impact.
- External data requirement change: see question below.
What's an "external data requirement change"?
Occasionally, regulators or third-party service providers may mandate additional data requirements for existing functionality. In these cases we will need to enforce the requirement for all clients who use the affected functionality. To minimise impact, we will likely introduce the third-party change requirement to all versions (to avoid needing to do a large upgrade to latest version). This situation has not yet arisen; if/when it does we will be in contact with full details.
Why do the API URLs include "/v1"?
The URL version is expected to stay as "v1" for the foreseeable future. However, it may be used at a later date for a complete API overhaul.