Versioning

Topics covered on this page

All available API versions

We regularly release updates to our API. Most of the time, these updates do not affect existing integrations and are therefore applied automatically to your account.

Once in a while though, our API updates are not compatible with previous releases. Because the new version may exhibit different attribute names or other breaking changes. In that case, we will create a new API version. As a user, you are free to update your account whenever you are ready from the dashboard. Test mode and Live mode can be updated independantly.

You can also perform any API call in the API version of your choice, by passing the Omise-Version header in your request. The version you pass through the header will have higher priority than the version set in your Opn Payments account. This is convenient for testing a new API version without updating your account. You can also ensure a zero-downtime deployment using this feature! Assuming you have an existing application running on API version 2017-11-02, you could update it to 2019-05-29 by:

Updating your code to handle the API update (See the upgrade guide to 2019-05-29 for an example.)
Passing the Omise-Version: 2019-05-29 header with your API calls to Opn Payments, so that your new code uses the new version.
Once your application has been deployed, you can update your account API version from the Dashboard so that all API calls will automatically default to 2019-05-29

Header example:

Omise-Version: 2019-05-29

All available API versions