定期課金APIの実装方法｜PAY.JPでプラン作成からキャンセルまでの流れを解説

サブスクリプション機能をこれから実装する開発者の方に向けて、PAY.JPの定期課金API（Subscription API）の実装方法を解説します。

プラン作成・顧客登録・定期課金開始のリクエスト例に加えて、実装に取りかかる前に済ませておくべき準備、各ステップで「成功した」と判断できる見方、テスト時にどこまで適当な値を使ってよいかなど、docs.pay.jpの複数のページに分かれて書かれている情報を、実際に手を動かす順番で1本にまとめました。

サブスクリプションの概念やビジネス面での特徴はサブスクとは？意味・仕組み・ビジネスモデルをわかりやすく解説で扱っているため、本記事は実装そのものにフォーカスします。

実装前の準備：テストキーと審査

この記事のコード例で使うsk_test_...というテスト用のシークレットキーは、PAY.JPのアカウント登録とメール認証を済ませた時点で発行されます。本番申請やカード会社の審査は、実際の決済（本番環境）を行う段階で必要になるものであり、テスト環境での実装・動作確認にはこれらの審査は不要です。つまり、本番申請の結果を待たずに、この記事の内容はすぐに試し始められます。

定期課金の実装方法は2つある

PAY.JPで定期課金を実現する方法には、次の2つがあります。

• 方法A：定期課金API（Subscription API）を利用する：Plan・Customer・Subscriptionを作成すれば、課金のスケジュール管理・実行はPAY.JP側が自動で行います
• 方法B：保存済みの支払い方法に対し、事業者側でバッチ処理を実施する：顧客に紐づいたカード（保存済みの支払い方法）に対して、通常の支払いAPIを事業者側が任意のタイミングで呼び出す方法です。「いつ課金するか」のスケジュール管理・失敗時のリトライ判断は、すべて自社側の実装・運用でカバーする必要があります
  

なお、PAY.JPにはv1とv2という2つのAPIバージョンがあります。v1は従来から提供されている実績のあるバージョン、v2は新しく提供が始まったバージョンで、対応する決済手段や機能がv1と異なります。

方法A（定期課金API）は現時点でv1限定の機能で、v2にはまだ提供されていません。方法B（自前バッチ処理）はv1・v2どちらでも実装できます。つまり、v2を使う場合は方法Bを選ぶことになります。

v1とv2の対応決済手段・機能の違いはAPI v1からv2への移行ガイド（docs.pay.jp）にまとまっています。

定期課金APIとは？構成要素とステータス

ここからは、方法A（定期課金API）の実装を解説します。定期課金APIを使う際は、主に3つのリソース（APIで操作するデータのまとまり）を組み合わせて使います。

• Plan（プラン）：金額・課金間隔（月次／年次）といった、料金体系そのものを定義するリソース
• Customer（顧客）：カード情報を紐付けた顧客を登録するリソース
• Subscription（定期課金）：PlanとCustomerを結びつけて、実際に自動課金を回す本体のリソース

定期課金にはstatus（ステータス）という状態を表す項目があり、active（アクティブ）・trial（トライアル中）・paused（一時停止）・canceled（キャンセル）の4種類の値を取ります。実装時にこのstatusをどう扱うべきかは、後述の「キャンセル・削除と状態管理の注意点」で解説します。詳細な仕様は定期課金を行う（docs.pay.jp）を参照してください。

実装の流れ：プラン作成→顧客登録→定期課金の開始

基本的な実装は、次の3ステップです。以下はcurl（コマンドラインからHTTPリクエストを送るツール）でのリクエスト例で、認証はHTTP Basic認証（ユーザー名とパスワードの組をリクエストに含めて本人確認を行う方式）を使い、シークレットキーをユーザー名として渡します。

1. プランを作成する

curl "https://api.pay.jp/v1/plans" \
-u "sk_test_••••••••••••••••••••••••": \
-d "id=normal" \
-d "amount=500" \
-d "interval=month" \
-d "currency=jpy"

各パラメータの詳細は定期課金を行う（docs.pay.jp）に譲りますが、currencyだけは注意が必要です。通貨を指定するパラメータですが、現状は日本円jpyのみサポートで、他の通貨は選べません。

レスポンスに指定したid（この例では"id": "normal"）を含むプランの情報が返ってくれば成功です。errorオブジェクトが返ってきた場合は失敗なので、次のステップには進めません。なおidは一意である必要があり、同じidで再度リクエストするとエラーになります。

2. 顧客を登録する

curl "https://api.pay.jp/v1/customers" \
-u "sk_test_••••••••••••••••••••••••": \
-d "email=subscriber@pay.jp" \
-d "id=cus_test" \
-d "card=作成したトークンID"

cardパラメータには、あらかじめカード情報をトークン化して取得したトークンIDを渡します（自社サーバーでカード番号を直接扱わずに済む仕組みで、詳しい手順はカード情報のトークン化（docs.pay.jp）を参照してください）。

テスト環境で試す際、email・idはどちらも任意項目のため適当な値で構いません（idを省略すると自動採番されます）。一方、トークンのもとになるカード番号だけは実在の番号ではなく、PAY.JPが指定するテストカード番号（例：4242424242424242）を使う必要がある点に注意してください。

こちらもレスポンスに指定したid（この例では"id": "cus_test"）を含む顧客の情報が返ってくれば成功です。

3. 定期課金を開始する

curl "https://api.pay.jp/v1/subscriptions" \
-u "sk_test_••••••••••••••••••••••••": \
-d "plan=normal" \
-d "customer=cus_test"

1で作成したPlanのid（normal）と2で作成したCustomerのid（cus_test）をそれぞれ指定するだけで、定期課金が開始されます。

このステップだけは成功の見方が少し異なります。トライアル・課金日指定なしのプランの場合、このリクエスト自体が初回課金の実行を兼ねているため、レスポンスのstatusが"active"（初回課金に成功）または"trial"（トライアル中で課金は発生しない）になっていれば成功です。初回課金に失敗した場合はSubscriptionオブジェクト自体が作成されず、1・2と同じくerrorオブジェクトが返ってきます（1・2の失敗が単純な入力エラーであるのに対し、3の失敗は「カードが使えなかった」という決済結果としての失敗を意味します）。

なお、上記はいずれもcurlでの例ですが、PAY.JPはRuby・PHP・Python・Java・Node.js・Perl・Goの公式クライアントライブラリを提供しており（ライブラリ一覧（docs.pay.jp））、実際のプロダクトではこれらのライブラリ経由で実装するのが一般的です。

トライアル・課金日・複数プランの設定

無料期間を設けたい場合は、trial_endにトライアル終了日時をUNIXタイムスタンプ（1970年1月1日からの経過秒数で日時を表す形式）で指定します。

curl "https://api.pay.jp/v1/subscriptions/更新する定期課金ID" \
-d trial_end=1483142400 \
-u "sk_test_••••••••••••••••••••••••":

毎月の課金日を固定したい場合は、月次プラン限定でbilling_day（1〜31日、または末日）を指定します。

curl "https://api.pay.jp/v1/plans" \
-u "sk_test_••••••••••••••••••••••••": \
-d "id=normal" \
-d "amount=500" \
-d "interval=month" \
-d "billing_day=31" \
-d "currency=jpy"

日割り課金の要否を指定するprorateパラメータも用意されており、これは後述のプラン変更時に使います。

料金が異なる複数のプラン（ベーシック・プレミアムなど）を用意したい場合は、1つのPlanに複数の料金を持たせる仕組みはないため、料金の数だけPlanを個別に作成します（例：id=basic, amount=500とid=premium, amount=2000をそれぞれ作成）。

顧客が後から別のプランに切り替える（アップグレード／ダウングレード）場合は、Subscriptionを作り直す必要はなく、更新用のエンドポイントに変更先のプランIDを指定するだけで済みます。

curl "https://api.pay.jp/v1/subscriptions/変更する定期課金ID" \
-u "sk_test_••••••••••••••••••••••••": \
-d "plan=変更先のプランID"

このとき、月の途中でプランが切り替わった分の金額調整に使われるのが、先ほどのprorateパラメータです。

キャンセル・削除と状態管理の注意点

定期課金を止める場合は、目的に応じて「キャンセル」と「削除」を使い分けます。

# キャンセル（履歴は残したまま停止する）
curl "https://api.pay.jp/v1/subscriptions/キャンセルする定期課金ID/cancel" \
-u "sk_test_••••••••••••••••••••••••": \
-XPOST

# 削除（定期課金そのものを削除する）
curl "https://api.pay.jp/v1/subscriptions/削除する定期課金ID" \
-u "sk_test_••••••••••••••••••••••••": \
-XDELETE

実装時にもう一点注意したいのが、定期課金の状態確認の仕方です。current_period_end（現在の課金期間の終了日時）はPAY.JP側のバッチ処理で更新されるため、たとえば期限が3/31でも、4/1になった瞬間に次の課金が実行されるわけではなく、実行まで多少のタイムラグがあります（月初は特に顕著）。課金が成功すればcurrent_period_endだけが進みstatusはactiveのまま、失敗して初めてstatusがpausedに変わります。つまり有料機能を止めるかどうかの判定には、current_period_endではなくstatusを使ってください（時刻で判定すると、課金処理を待っているだけの正常な会員を誤って期限切れにしてしまう恐れがあります）。

このほか、PAY.JP側で障害が発生した場合は安全のため定期課金が一時的に全停止され、復旧後に遅延分がまとめて再実行されます。またpausedは障害時だけでなく、2回目以降の課金に失敗した場合にも自動的に遷移しますが、再開には「再開（resume）」操作が別途必要です。

決済失敗の原因・対策は継続課金の決済が失敗する原因と対策、カード有効期限切れへの事前対策はサブスクの「カード更新切れ」対策、詳細な仕様は定期課金を行う（docs.pay.jp）を参照してください。

PAY.JPで定期課金APIを実装する

PAY.JPの定期課金APIは、プラン作成・顧客登録・定期課金開始という3ステップのシンプルな構成で実装でき、公式ドキュメント・公式クライアントライブラリも一通り揃っています。決済手段はクレジットカード・Apple Pay（Web/アプリ）に対応しています。対応範囲をシンプルに保つことで、実装から本番リリースまでのスピードを重視したい開発者に向いています。

料率はプランによって異なり、月額0円のスタンダードプランは3.3%、月額20,000円のビジネスプランは2.78%、月額50,000円のエンタープライズプランはVisa・Mastercardが2.59%・その他ブランドが2.7%です（詳細は料金プランを参照）。

エンタープライズプランのVisa・Mastercard料率2.59%は、国内の主要な決済代行サービスと比べても最安水準です。

定期課金の技術仕様をさらに詳しく確認したい場合は定期課金を行う（docs.pay.jp）を、運用面の設定方法は定期課金についてのヘルプも合わせて参照してください。

まとめ

• PAY.JPで定期課金を実現する方法は「定期課金API（本記事、方法A）」と「保存済みの支払い方法への自前バッチ処理（方法B）」の2つがある
• 実装を始めるにはPAY.JPのアカウント登録とメール認証が必要だが、テスト環境での実装・動作確認自体に本番申請・カード会社審査は不要
• 実装の基本フローは「プラン作成→顧客登録（カードのトークン化を含む）→定期課金の開始」の3ステップ。1・2はレスポンスにidが返れば成功、3だけはstatusがactive/trialになっているかで初回課金の成否まで分かる
• トライアル期間はtrial_end、課金日はbilling_dayで設定できる。料金が異なる複数プランは料金の数だけPlanを作成し、既存の定期課金のプラン変更は更新エンドポイントでplanを差し替えるだけで済む
• ステータスはactive/trial/paused/canceledの4種類で、有料期間の判定にはcurrent_period_endではなくstatusを見るのが推奨される。pausedには障害発生時のほか課金失敗時にも自動的に遷移するが、Stripeのような自動リトライはなく「再開」操作が必要
• PAY.JPの定期課金APIを実際に試してみたい方は、サービス内容を確認してみてください