Transfer 廃止に伴う移行ガイド

PAY.JP では、売上預かり金やその入金状態を表現するために、これまで Transfer/TenantTransfer オブジェクトをご提供してまいりました。しかし、より機能を充実させるため、新しい入金管理オブジェクトへの移行を行うことになりました。

以下のドキュメントも併せてご参照いただき、移行対応をお願いいたします。

更新履歴

初回のドキュメント公開からリリース日までの更新履歴です。

日付 対象箇所 更新内容
2024/5/29 statementオブジェクト type に misc を追加しました。
subjectに plan_fee other を追加しました。
2024/5/29 balanceオブジェクト closed_date プロパティを追加しました。
2024/5/29 termオブジェクト closed プロパティを追加しました。
2024/5/20 取引明細一括ダウンロードURLを発行 Balanceオブジェクトに含まれる取引明細を一括ダウンロードする機能を追加しました。
2024/5/7 締めサイクルと売上集計 Statementオブジェクトに関するセクションを追加しました。
全体的に説明を詳細化しました。
2024/5/7 移行ガイド(本ページ) API/仕様上の主な変更点>最後のTransferが入金繰越であった場合の挙動について を追加しました。
2024/4/11 statementオブジェクト net プロパティを追加しました。
2024/4/8 termオブジェクト created プロパティを削除しました。
2024/4/8 balanceオブジェクト tenant_id プロパティを追加しました。
type プロパティを state にリネームしました。
statements プロパティを listオブジェクト から オブジェクトのリスト に変更しました。
2024/4/8 statementオブジェクト tenant_id および type プロパティを追加しました。
2024/4/8 取引明細リストを取得 only_sales パラメーターを削除しました。
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が入金繰越であった場合の挙動について

6/1 に行われる最後の Transfer 締め処理の結果が「入金繰越」となった場合は、その時点で繰り越されている金額と同額の Statement が作成され、Balance に追加されます。

Transfer は入金繰越状態のままとなります。

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

現在の 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 の一覧を取得

画面イメージ

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

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