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

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

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

リリースされたOpn Payments 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規格との整合性を高めるため、すべての通貨がデフォルトで大文字になります（例：thbはTHB）。

優れた整合性

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

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

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

互換性を破る変更

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

互換性のある変更点

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