Transfer廃止に伴う移行ガイド

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/仕様上の詳細な変更点

加盟店様でご対応いただきたいこと

現在の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/balances/
  • balanceとそれに含まれるstatementを一覧します
  • GET /v1/balances?tenant=(対象TenantのID)から、balanceの一覧を取得

画面イメージ


上記に加えて、各オブジェクトの詳細を表示する画面を必要に応じて用意します。

取引明細の詳細を表示する画面
取引明細ダウンロード画面
残高詳細画面