アップグレード・ガイド 2019-05-29

Omise APIのベストバージョン、2019-05-29が一般向けにリリースされました。

このガイドは、今回リリースされた最新のアップグレードを十分ご活用いただけるよう加盟店の皆様のために準備されました。このアップグレードは自動で行われません。このガイドを読んでいただき、アプリケーションに必要な変更を加えた後、加盟店様にとってふさわしいタイミングでアカウントをアップグレード していただけます。詳細については、APIバージョンガイドをご覧ください。

アップグレードの前にアプリケーションテストを徹底的に行ってください。このガイドで説明されている点を考慮せずにアップグレードすると、アプリケーションが機能しなくなる恐れがあります。

リリースされたOmise APIのバージョン2017-11-02では、Source(ソース)API が導入され、増加していく決済方法を受け入れてきました。今回リリースされるバージョン2019-05-29では、残念ながら互換性のない変更が加えられましたが、より一層の整合性と直感性を高めるものとなっています。

このガイドで説明される点は以下の通りです。

  1. 新しいアカウント互換性のエンドポイント 
  2. APIの広範囲な変更とその理由
  3. 具体的な、互換性のない変更点
  4. 互換性を破らない変更点の選択

最後の部分で、いくつかの「互換性のある変更点」をリスト化しています。新しいドキュメントは、/docsからご確認いただけますが、上記ページのドロップダウン・メニューから、以前のバージョンのドキュメントもご確認いただけます。

新しいアカウント互換性のエンドポイント

アカウントが「ゼロ金利分割払い」に設定されているかどうか、受け入れ可能な決済方法は何か、どの銀行が送金を行なっているかなど、アカウントに関する追加情報を取得できる新しいアカウント「互換性」エンドポイントを導入しました。この情報は加盟店のパブリックキー(公開鍵)を使ってアクセス可能なので、あるプラグインにおいて、特定のアカウントがどの決済方法をサポートしているかを確認する際に役立ちます。 詳細は/capability-apiを参照してください。

新しいネーミング事例

日時の値(例:2020-01-01T00:00:00Z) を表す動詞の過去形を使用するすべての属性(例えばcreated, refunded等)に接尾語_atが追加されます。こうした動詞は、ブール値専用となっています。例えば、createdの属性は、2019-05-29バージョンではcreated_atとしてシリアル化されます。

日付の値を表す属性(例:2020-01-01)に_on接尾語が追加されます。例えば、receipt(レシート)の属性はissued_onに変更されました。

ISO 4217規格との整合性を高めるため、すべての通貨がデフォルトで大文字になります(例:thbTHB)。

優れた整合性

JSONレスポンスに関しては、エンドポイント間でもエンドポイント内でも、より整合性のある構造となりました。例えば、以前のバージョンでは、クレジットカード情報が削除された際にはほぼ全ての元の属性がレスポンスから削除されていましたが、今バージョンから該当オブジェクトは削除前のオブジェクトと同様となります。2017-11-022019-05-29のJSONレスポンスを比較してください。可能な場合には、APIレスポンスに標準のライブモードロケーション情報が含まれるようになりました。

schedule.statusの可能値を更新したことにより、active(アクティブ)ステータスがrunnning(実行中)となることで、ステータスがrunnning(実行中)または expiring(期限切れ)の場合、新しく追加された属性active(アクティブ)がtrueを返します。これはrunnning(実行中)、及びexpiring(期限切れ)のスケジュール、両方を返す検索フィルタをアクティブにする、スケジュールサーチスコープがより適切に動作する目的で変更されました。

銀行口座の構造に関しては現在、世界中で標準化されています。

互換性を破る変更

各オブジェクトのレスポンスに対する互換性を破る変更点を以下にまとめます。

オブジェクト  以前の属性   変更後の属性 注意点
account id team team2019-05-29以前のid値を反映しています。2019-05-29idはご自身のアカウント固有のIDとなります。
balance reserve_amount reserve
balance available transferable
bank account account_type type
charge refunded refunded_amount
dispute transaction transactions 一回のチャージバックで複数の取引を扱うことができます。
forex from base Investopedia: Base Currencyを参照してください。
forex to quote Investopedia: Quote Currencyを参照してください。
receipt date issued_on
occurrence schedule_date scheduled_on scheduleの最後にあるdにご注意ください。
occurrence retry_date retry_on
schedule start_date start_on
schedule end_date end_on
schedule next_occurrence_dates next_occurrences_on “occurrences”の最後にある”s”にご注意ください。
source installment_terms installment_term 分割払い用語は単数形になり、文字列ではなく整数としてシリアル化されます。
transaction type direction
transaction source origin Source(ソース)APIとの競合のため変更されました。
transfer transaction transactions 一回の送金で複数の取引を扱うことができます。

互換性のある変更点

互換性のある変更点に関して、例えばエンドポイント・レスポンスに新しい属性を定期的に追加するなど、基本的にAPI利用者のご希望に沿ったものとなります。以下のリストは、APIバージョン2019-05-29へ追加される一部のリストですが、この変更も全てのバージョンに順次反映されていきます。

オブジェクト 変更点
account team
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
transfer deleted, fee_vat, net, and total_fee
transaction key