PAY.JP では、売上預かり金やその入金状態を表現するために、これまで Transfer/TenantTransfer オブジェクトをご提供してまいりました。しかし、より機能を充実させるため、新しい入金管理オブジェクトへの移行を行うことになりました。
以下のドキュメントも併せてご参照いただき、移行対応をお願いいたします。
更新履歴
初回のドキュメント公開からリリース日までの更新履歴です。
| 日付 | 対象箇所 | 更新内容 |
|---|---|---|
| 2024/4/11 | Statementオブジェクト | net プロパティを追加しました。 |
| 2024/4/8 | Termオブジェクト | created プロパティを削除しました。 |
| 2024/4/8 | Balanceオブジェクト | tenant_id プロパティを追加しました。 |
| 2024/4/8 | Balanceオブジェクト | type プロパティを state にリネームしました。 |
| 2024/4/8 | Balanceオブジェクト | statements プロパティを listオブジェクト から オブジェクトのリスト に変更しました。 |
| 2024/4/8 | Statementオブジェクト | tenant_id および type プロパティを追加しました。 |
| 2024/4/8 | 取引明細リストを取得 | only_sales パラメーターを削除しました。 |
| 2024/4/8 | 取引明細リストを取得 | type パラメーターを追加しました。only_salesと同内容の検索がtype=salesの指定で行えます。 |
変更の概要
- 6月1日以降、Transfer/TenantTransfer オブジェクトの追加、更新が停止されます。
- 発行済みのオブジェクトや API などは維持されます。
- 将来的にデータ削除や API 廃止が行われる際は、別途告知期間を設けた上で実施いたします。
- 新たに Term オブジェクト、Balance オブジェクトが追加されます。
- すでにリリース済みの Statement オブジェクトと合わせて、Transfer の機能が代替される形になります。
- 6月1日以降は、Transfer の代わりに Term、Balance が発行されるようになります。
追加されるオブジェクトの概要
追加されるオブジェクトは、Transfer/TenantTransfer が持っていた以下の役割を分割したものになります。
- 締め区間を持ち、その区間の決済オブジェクトをまとめる。
- Term オブジェクト
- 締め処理によって集計された売上などの金額を保持する。
- Statement オブジェクト
- 残高の入金・入金繰越・返品超過請求の状態を管理する。
- Balance オブジェクト
移行スケジュール
| 日付 | 内容 |
|---|---|
| 2024/03/01 | APIドキュメントおよび移行ガイドのご案内 |
| 4月中旬 | サンプル加盟店アカウントのご提供開始 |
| 6/1 | 本番環境へのリリース |
| 6/15 | 移行後初回締め処理 |
サンプルアカウントについて
Term, Statement, Balance のデータが入ったサンプル加盟店アカウントを4月中旬頃にご提供予定です。
新 API を使った画面の動作試験にご利用ください。
API/仕様上の詳細な変更点
- 現在、決済に関する取引明細の 1 項目として記載されている「振込手数料」が、独立した Statement として発行されるようになります。
- 支払いオブジェクトに
term_idが追加されます。これは検索条件としても使用可能になります。- APIリファレンス - 入金の内訳を取得で提供していた機能は、支払いリストを取得に
term引数を指定することで代替されます。
- APIリファレンス - 入金の内訳を取得で提供していた機能は、支払いリストを取得に
- 締め区間の長さが、区間開始時点で決定されるようになります。
- 取引明細オブジェクトに、term と balance_id が追加されます。
加盟店様でご対応いただきたいこと
現在の Transfer オブジェクト/API のご利用方法に応じて、移行対応が必要になります。
PAY.JP管理画面上の「入金」メニューをご利用の場合
Term/Statement/Balance を使った同等の画面が用意されますので、そちらをご利用ください。
追加される管理画面に関するヘルプは、追ってご案内差し上げます。
Transferのイベントをご利用の場合
Transfer のイベントとしては、transfer.succeeded と tenant_transfer.succeeded が「入金内容の確定」イベントとして定義されています。
対応する新しいオブジェクトのイベントのうち、近いものとしては balance.fixed（入金/請求金額の確定）があります。
イベントは他にも追加されていますので、それらも合わせて加盟店様のシステム上での利用方法をご検討ください。
管理画面のメール通知機能には、2024年6月1日以降に balance.fixed が追加されますので、必要に応じて有効化の作業をお願いいたします。
Transfer/TenantTransfer APIを利用して独自の画面を構築している場合
新しいオブジェクトの API を使って画面を再構築していただく必要があります。
とくに、PAY.JP Platform をご利用の場合は、インボイス提示義務の関係から各テナント向けの TenantTransfer および対応する Statement の表示ページを開発されていることが多いかと存じます。
そのようなご利用パターンに対して、以下のようなページを想定し、改修方針の一例を示します。
前提
- Platformer 様が提供する、テナント向け管理サイト
- テナントのログイン後に表示されるページ
- ログイン情報から、対象テナントの ID が特定できている
- 例示しているURLはイメージであり、リンク先に実アプリケーションがあるわけではない点にご注意ください。
改修後のページ構成
オブジェクトが3種類に分かれるため、どのオブジェクトを基準に画面を構成するかを検討する必要があります。
締め区間ごとの決済に対する取引明細の一覧を表示したい場合
- https://example.platform/sales/
- term から作られた statement を一覧します
- GET /v1/statements?tenant=(対象 Tenant の ID)&type=sales から、売上に関する Statement の一覧を取得
画面イメージ
振込手数料などを含むすべての取引明細の一覧を表示したい場合
- https://example.platform/statements/
- テナントに発行された statement を一覧します
- GET /v1/statements?tenant=(対象 Tenant の ID)から、Statement の一覧を取得
画面イメージ
残高の状況を表示したい場合
- https://example.platform/balances/
- balance とそれに含まれる statement を一覧します
- GET /v1/balances?tenant=(対象 Tenant の ID)から、balance の一覧を取得
画面イメージ
上記に加えて、各オブジェクトの詳細を表示する画面を必要に応じて用意します。
取引明細の詳細を表示する画面
- https://example.platform/statements/(StatementのID)
- statement の詳細を表示します
- GET /v1/statements/(Statement の ID) から Statement を取得
取引明細ダウンロード画面
- https://example.platform/statements/(StatementのID)/invoice
- POST /v1/statements/(Statement の ID)/statement_urls から取引明細のダウンロード URL を取得
- 取得した URL にリダイレクトさせる
残高詳細画面
- https://example.platform/balance/(BalanceのID)
- GET /v1/balances/(Balance の ID) から残高オブジェクトを取得