API v1 からの移行について
現在 PAY.JP API v1 を利用中の方向けに、API v2 への移行に必要な事項を説明します。
API v2 ご利用の準備
現在 API v2はベータ版として一部のアカウントのみご利用いただけます
PayPay 決済をご利用予定の場合、すでにクレジットカード決済で本番申請済みであっても追加の審査が必要です。本番申請の必要箇所を改めてご入力いただき、審査結果をお待ちください。
API v2 への移行の概要
API v1 と API v2 は一部の API リソースで同じ ID のデータを共有できますが、基本的には別の API 群として提供されており、利用する SDK や必要な実装も異なります。 システム切り替え期間中は API v1 と API v2 を併用できますが、最終的には API v2 への完全な切り替えが必要です。
API v1 で作成された決済に対する返金等の操作は API v1 で行う必要があります。API v2 の利用開始後も API v1 で作成した決済への返金等が必要な期間は API v1 を利用可能な状態を維持してください。
API v1 で作成された Charge の返金期限は売上作成日から180日間です。 操作内容によっては PAY.JP 管理画面からも対応可能ですので、API v1 利用終了までの移行期間の対応方法をご検討ください。
API v1 と v2 の差分
API v1 と API v2 の主な差分は以下の通りです。
| API v1 | API v2 | |
|---|---|---|
| 利用可能な支払い手段 | カード、Apple Pay(アプリ/Web) | カード、Apple Pay(Web)、PayPay |
| 定期課金API | 提供あり | 未対応 ※ 2026年対応予定 |
| モバイルアプリ SDK | iOS/Android/Flutter/React Native | 提供なし ※ Checkout v2 をアプリ外決済ページとしてご利用いただけます。 |
| 対応プロダクト | PAY.JP、PAY.JP Platform | PAY.JP ※Platformは2026~2027年対応予定 |
APIキー
API v2 でも API v1 と同じ API キーを使用します。
API v1 と API v2 のオブジェクト
決済情報
API v2 では決済情報は Payment Flow (支払い管理オブジェクト)API オブジェクトで表現されます。 API v1 の Charge オブジェクトとは別物ですので、それぞれ対応する API を使用して操作してください。
Customer と関連情報
Customer (顧客)API オブジェクトは API v1 と API v2 で同一のオブジェクト ID を利用できます。
API v1 で作成した顧客は API v2 でも同一のIDの Customer として利用できます。 また Customer に紐づいた Card については、対応するPayment Method (支払い方法)APIオブジェクトが自動的に作成されています。 ただし、API v2 で作成した PaymentMethod は API v1 からは利用できません。
API v1 で作成した Card に対応する PaymentMethod の情報を取得するには カード ID で対応する Payment Method を取得する API をご利用ください。
カードの3Dセキュア認証について
API v2 では全てのカードは初回決済時までに3Dセキュア認証が必要です。 API v1 で登録されたカードのうち 3D セキュア認証が未実施のものを API v2 で決済に利用する場合、3D セキュア認証フローが実行されます。 サーバーサイドからリクエストしていた場合は、該当の決済に対して フロントエンドでの requires_action の対応 を実施する必要があります。
その他のオブジェクト
以下のオブジェクトも API v1 と API v2 で同一のオブジェクト ID を利用できます。 利用する API のバージョンによって一部レスポンスの内容が異なる場合がありますのでご注意ください。
データ形式の変更
Customerオブジェクトのdefault_cardフィールドは API v2 では廃止され、代わりにdefault_payment_methodフィールドが導入されました。- v1 では
Cardオブジェクトにcvc_checkとaddress_zip_checkフィールドがありましたが、v2 のPaymentMethod(type=card) ではこれらのフィールドは廃止されました。 - API v2では
Customer.emailのバリデーションが強化され、RFC 5322 に準拠した形式が必要です。 - Metadata のバリューに JSON で扱える型（文字列、整数、ブール値）を使用できるようになりました。