サブスク決済の実装方法｜準備から設計の判断ポイントまで解説

サブスク（サブスクリプション）決済をPAY.JPの定期課金APIで実装する開発者の方に向けた記事です。

APIリファレンス（docs.pay.jp）にはAPIの呼び出し方やパラメータの仕様が掲載されていますが、実装を始める前に何を準備すべきか、エラーハンドリングや自動リトライをどう設計すべきかといった実務的な判断ポイントまでは書かれていません。本記事では、その実装前の準備と設計判断に絞って解説します。

サブスクリプションの概念やビジネス面での特徴はサブスクとは？意味・仕組み・ビジネスモデルをわかりやすく解説を、定期課金APIそのものの仕様（ステータス管理・イベントの発生条件など）は定期課金APIの実装方法｜PAY.JPでプラン作成からキャンセルまでの流れを解説で詳しく解説しています。

実装を始める前に準備しておくこと

コードを書き始める前に、次の3点は用意・決定が必須で、加えて1点は準備しておくことを強く推奨します。

1. アカウント登録とAPIキーの取得：PAY.JPにアカウント登録すると、まずテスト用のAPIキー（sk_test_...／pk_test_...）が発行され、すぐに開発を始められます。実際の決済を行う本番用キーを使うには、別途本番申請（加盟店としての審査）が必要になるため、リリース時期から逆算して早めに申請しておくと安心です（詳細はお申し込み・利用・審査についてを参照）
2. 使用する言語のクライアントライブラリを選ぶ：PAY.JPはRuby・PHP・Python・Java・Node.js・Perl・Goの7言語に対応した公式ライブラリを提供しています。自社のサーバーサイドの言語に対応しているか、あらかじめ確認しておきましょう
3. フロントエンド側の決済フォームを用意する：カード番号を自社サーバーに送らず、公開鍵を使ってブラウザ上でトークンIDに変換する画面（トークン化）が必要です（詳細はカード情報のトークン化（docs.pay.jp）を参照）
4. （推奨）Webhookの受信エンドポイントを用意する：定期課金の作成・課金自体はWebhookがなくても行えます。ただし、課金の成功・失敗やステータスの変化は、Webhook（イベントが発生するたびにPAY.JP側から指定のURLへ自動的に通知が届く仕組み）を使わない場合、APIに都度問い合わせて確認する運用になり、検知が遅れたりAPIの呼び出し回数が増えたりします。定期課金が失敗して停止したことにすぐ気づけるよう、実務上は用意しておくことを強く推奨します

つまり、1〜3のAPIキー・言語ライブラリ・決済フォームは実装を始めるための必須条件、4のWebhookは運用を見据えた推奨事項という位置づけです。

実装の全体像

決済フォームでのカード情報のトークン化から、サーバー側でのプラン作成・顧客登録・定期課金開始までの流れは、次の4段階です。

1. 決済フォームでカード情報をトークン化する
2. プランを作成する
3. 顧客を登録する
4. プランと顧客を結びつけて定期課金を開始する。

実は、PAY.JPで定期課金を実現する方法には2種類あります。1つは本記事で解説している定期課金API、もう1つはcustomerに紐づいた支払い方法（payment method）に対して、事業者側が任意のタイミングでバッチ処理を呼び出し、都度課金する方法です。

どちらの方法が使えるかは、利用しているAPIのバージョン（v1／v2）によって変わります。v1・v2の違いを端的に言うと、v1は従来から提供されている実績のあるバージョン、v2はPayPayなど新しい決済手段に対応した新しいバージョンです。APIがv1であれば、シンプルに実装できる定期課金API（本記事の内容）がおすすめです。v2であれば、定期課金APIが現時点で未対応（2026年対応予定）のため、自社でバッチ処理を組んで都度課金する方法を選ぶことになります。

v1・v2の違いについて詳しくはAPI v1からv2への移行ガイド（docs.pay.jp）を参照してください。

具体的なリクエスト例やパラメータの詳細は定期課金APIの実装方法にまとめているため、本記事ではここから先、実装時に判断が必要になるポイント（停止・再開・キャンセル、エラーハンドリング、自動リトライ）に絞って解説します。なお、次の「停止・再開・キャンセルの実装」は定期課金APIを前提にした内容です。

停止・再開・キャンセルの実装

運用中の定期課金を「停止（pause）」「再開（resume）」「キャンセル（cancel）」する処理は、いずれの言語でも「対象の定期課金IDを取得してから、そのオブジェクトに対して操作用のメソッドを呼び出す」という共通のパターンで実装します。Node.jsの例は次のとおりです。

// Node.js：キャンセル
payjp.subscriptions.cancel('sub_xxx');

// Node.js：停止
payjp.subscriptions.pause('sub_xxx');

// Node.js：再開
payjp.subscriptions.resume('sub_xxx');

Rubyであればsubscription = Payjp::Subscription.retrieve('sub_xxx')でオブジェクトを取得したうえでsubscription.cancelのようにメソッドを呼び出す形になり、PHP・Pythonも同様の「取得してから操作する」構成です。

実装時に気をつけたいのは、「キャンセル」と「削除」は別物という点です。キャンセル（cancel）はすぐに定期課金を止めるのではなく、statusがcanceledになったうえで、現在の課金期間の終了日（current_period_end）を迎えたタイミングで自動的に削除される「予約解除」に近い挙動です。削除が完了する前であれば、再開（resume）リクエストでキャンセルを取り消すこともできます。

一方、削除（delete）は即座に定期課金を消す操作で、こちらは取り消せません。削除後は通常の定期課金情報取得APIでは参照できなくなり、確認するにはイベント情報取得APIを使う必要があります。また、同じ顧客が同じプランに重複して登録することはできないため、一度キャンセルした顧客を同じプランに戻したい場合は、新規作成ではなく再開を使う必要があります。

課金失敗時に自動的にpaused（停止）状態へ切り替わる仕様など、ステータスのより詳しい扱いは定期課金APIの実装方法にまとめています。

設計の判断ポイント：エラーハンドリングとリトライ設計

実装前に、次の2点は必ず確認して設計に組み込んでください。

① エラーの受け取り方は、使う言語のドキュメントで確認してから実装する

PAY.JPの公式ライブラリは、エラーを「例外」で返す言語（Python・Ruby・PHP・Java）と、「戻り値やコールバックのエラーオブジェクト」で返す言語（Node.js・Go）が混在しています。他言語のサンプルコードのエラー処理をそのまま自分の言語に置き換えると、正しく動きません。実装前に、自分が使う言語のエラーの受け取り方をAPIリファレンス（docs.pay.jp）の該当言語タブで確認してください。

② 自動リトライはデフォルトで無効なので、明示的に設定する

PAY.JPのAPIには負荷防止のためのレートリミットがあり、特にテスト用キーでは秒間2リクエストという小さな制限です。公式ライブラリには自動リトライの設定機能がありますが、デフォルトは「リトライなし」です。

設定しないままテストや負荷の高い処理を行うと、レートリミットに達した際に429エラーがそのままアプリケーションに返ってきます。実装の初期段階で、自動リトライを設定するか、429エラーを受け取った際の再試行処理を自前で用意してください（詳細はAPIリファレンス（docs.pay.jp）のRate Limitの項を参照）。

運用時に気をつけたいポイント

コードを書いて動かすだけでなく、実際に運用に乗せる際には次のような点を事前に検討しておくと安心です。

• 課金結果の検知はWebhookで行う：課金の成功・失敗はAPIを定期的に呼び出して確認するのではなく、Webhookで受け取るのが基本です。仕組みの詳細はWebhookの実装方法を参照してください
• 顧客・プラン・課金履歴をどう自社DBに保持するか決めておく：PAY.JP側にも顧客・プラン・定期課金の情報は保持されますが、退会理由の分析やMRR（月次の継続収益）の集計など自社での分析を行う場合は、Webhookで受け取ったイベントを自社DBにも記録しておく設計が必要になります
• カードの有効期限切れへの備え：定期課金では、カードの有効期限切れによる課金失敗が頻繁に発生します。事前の通知・催促といった対策はサブスクの「カード更新切れ」対策にまとめています
• 決済が失敗した場合の通知フロー：課金に失敗した場合、PAY.JPには自動リトライの機能がないため、通知や再開操作までを実装側で用意する必要があります。詳しくは継続課金の決済が失敗する原因と対策を参照してください

PAY.JPでサブスク決済を実装する

PAY.JPの定期課金APIは、Ruby・PHP・Python・Java・Node.js・Perl・Goの公式クライアントライブラリを提供しており、プラン作成・顧客登録・定期課金開始という共通のシンプルな流れで実装できます。カード情報のトークン化にも対応しているため、PCI DSSへの対応範囲を抑えながら実装を進められます。定期課金機能を追加するための費用はかからず、通常のカード決済と同じ決済手数料のみで利用できます。

料率はプランによって異なり、月額0円のスタンダードプランは3.3%、月額20,000円のビジネスプランは2.78%、月額50,000円のエンタープライズプランはVisa・Mastercardが2.59%・その他ブランドが2.7%です（詳細は料金プランを参照）。API全体の仕様はAPIリファレンス（docs.pay.jp）、運用面の設定方法は定期課金についてのヘルプも合わせて参照してください。

まとめ

• 実装前にAPIキー・言語ライブラリ・決済フォームの準備が必須（詳細は#29）。定期課金APIのほか自社バッチによる都度課金もあり、v2では都度課金が唯一の選択肢
• 停止・再開・キャンセルは共通パターンで実装できるが、「キャンセル」は期間終了まで待つ予約解除に近い挙動、「削除」は取り消せない即時操作という違いに注意
• エラーの受け取り方は言語で異なるため、自分の言語のドキュメントで確認する。自動リトライはデフォルトオフのため明示的な設定が必要
• 運用時はWebhookでの結果検知、自社DBでの管理、カード有効期限切れ・決済失敗への対策を検討しておく。追加費用なく利用できるので試してみてほしい