Topics covered on this page
We’re proud to announce the general availability of the best version
of the Omise API yet:
This is an upgrade guide for you, the merchant, to make sure your applications benefit from the latest improvements. As always, you will not be upgraded automatically. Instead, once you’ve read through this guide and implemented the necessary changes in your application, you can upgrade your account at a time convenient for you. See our API Versioning guide for more detail.
Please test your application thoroughly before upgrading your account version. Your application will break if you upgrade without addressing the changes outlined in this document.
Note: Webhook events are always serialized according to your account version as of the time of the event trigger regardless of the version specified in the triggering request.
The previous major version of the Omise API was
version introduced the Source API enabling the
growing number of payment methods we’ve since
released. With this version,
2019-05-29, we are aiming for better
consistency and intuitiveness, which, unfortunately, necessitated a
few breaking changes.
In this guide, we will describe:
- The new Account Capability endpoint
- Broader changes to the API and their motivations
- Specific breaking changes
- A selection of non-breaking changes
The new docs are published, as usual, at /docs, but you can always retrieve previous versions by selecting your desired version from the dropdown above.
New Account Capability Endpoint
We’ve introduced a new account
capability endpoint which allows you
to retrieve additional information about your account including
whether your account is set up for
zero interest installments, which
payment methods are accepted, and which banks supported for transfers.
This information is accessible using your public key making it
easy to use in conjunction with the Source API. See
Capability API for more details.
New Naming Conventions
All attributes using the past tense of verbs (e.g.
refunded, etc.) which represent
2020-01-01T00:00:00Z) now have an
_at suffix. For instance,
created attributes will now be serialized as
created_at as of
2019-05-29. Past tense verbs will be reserved for booleans
values only. For instance,
charge.reversed (which represents
whether a charge has been reversed) remains unchanged, while
charge.refunded (which represented an amount value) has become
Attributes which represent
date values (e.g.
2020-01-01) now have
_on suffix. For instance, the
receipt.date attribute has been
All currencies are now upcased by default (e.g.
for better alignment with the ISO 4217
JSON responses now have a more consistent structure both across and
within endpoints. For example, in previous versions, when
successfully deleting a card, most of the original attributes were
stripped in the response. Now, the object should look the same as
pre-deletion: compare the JSON responses from
2019-05-29. Where possible,
API responses now include standard
We have updated the possible values for
schedule.status: the status
active has been renamed
running. The newly added attribute
true if the
This change was made to better align with the behavior of the schedule
search scopes which has a search filter
Bank account structure is now standardized across countries.
Specific Breaking Changes
The following table summarizes the breaking changes on each object:
|object||old field||replacement field||notes|
||For Thailand and Singapore, the bank code (e.g.
TMB Bank) is found at
||A single dispute can have multiple transactions|
||See Investopedia: Base Currency|
||See Investopedia: Quote Currency|
dat the end of
sat the end of
||We have updated the possible values (see Better Consistency)|
||Installment term is now singular and serialized as an integer rather than a string|
||Replaced due to conflict with Source API|
||A single transfer can have multiple transactions|
We add new attributes to endpoint responses regularly. What follows
is a non-exhaustive list of these additions to API version
2019-05-29 which should find their way into all versions soon.