Upgrade Guide 2019-05-29

We’re proud to announce the general availability of the best version of the Omise API yet: 2019-05-29.

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 2017-11-02. This 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:

  1. The new Account Capability endpoint
  2. Broader changes to the API and their motivations
  3. Specific breaking changes
  4. 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. created, refunded, etc.) which represent datetime values (e.g. 2020-01-01T00:00:00Z) now have an _at suffix. For instance, created attributes will now be serialized as created_at as of version 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 charge.refunded_amount.

Attributes which represent date values (e.g. 2020-01-01) now have an _on suffix. For instance, the receipt.date attribute has been replaced with receipt.issued_on.

All currencies are now upcased by default (e.g. thb becomes THB) for better alignment with the ISO 4217 standard.

Better Consistency

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 2017-11-02 to 2019-05-29. Where possible, API responses now include standard livemode and location.

We have updated the possible values for schedule.status: the status active has been renamed running. The newly added attribute active returns true if the status is running or expiring. This change was made to better align with the behavior of the schedule search scopes which has a search filter active which returns both running and expiring schedules.

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
account id team team now reflects pre-2019-05-29 id value; 2019-05-29 id now is identifier specific to your account
balance reserve_amount reserve
balance available transferable
bank account account_type type
bank account brand bank_code For Thailand and Singapore, the bank code (e.g. tmb) is now found at bank_code. For all countries, the bank name (e.g. "TMB Bank") is found at brand
charge refunded refunded_amount
dispute transaction transactions A single dispute can have multiple transactions
forex from base See Investopedia: Base Currency
forex to quote See Investopedia: Quote Currency
receipt date issued_on
occurrence schedule_date scheduled_on Note the "d" at the end of "schedule"
occurrence retry_date retry_on
schedule start_date start_on
schedule end_date end_on
schedule next_occurrence_dates next_occurrences_on Note the "s" at the end of "occurrence"
schedule status We have updated the possible values (see Better Consistency)
source installment_terms installment_term Installment term is now singular and serialized as an integer rather than a string
transaction type direction
transaction source origin Replaced due to conflict with Source API
transfer transaction transactions A single transfer can have multiple transactions

Non-Breaking Changes

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.

object added
charge fee, fee_vat, interest, interest_vat, and net
charge schedule default_card
dispute funding_amount and funding_currency
document deleted and download_uri
recipient deleted and metadata
refund funding_amount, funding_currency, and status
schedule active
transfer deleted, fee_vat, net, and total_fee
transaction key