Upgrade Guide 2019-05-29
Topics covered on this page
We’re proud to announce the general availability of the best version
of the Opn Payments 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 Opn Payments 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:
- 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. 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 dat 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 sat 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 |
