定期課金

PAY.JP では、定期課金を簡単に組み込むための API を提供しています。ここでは、定期課金の実装方法について説明します。

プランの作成

まず、定期課金を行うためのプランを作成します。プランでは、金額、トライアル日数、期間、課金日などの詳細な設定が可能です。たとえば、月額500円のノーマルプラン、年額5,000円のゴールドプランなど、定期課金のタイプに応じて適したプランを使い分けることができます。

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

顧客登録と定期課金の開始

次に、定期課金の対象となる顧客を作成します。 顧客にはクレジットカード情報を紐付ける必要があります。

（引数 id の指定は任意です）

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

カード情報が正常であれば、顧客の作成に成功します。

レスポンスの顧客 ID cus_test と課金を行うプランを紐付けて、定期課金リクエストを送信します。

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

PAY.JP の定期課金は前払い式です。上記の例のように課金日やトライアルを指定しない場合、定期課金の作成と同時に即座に課金が行われます。
後述する課金日の指定やトライアルを設定することで、課金タイミングを任意に調整できます。

課金のタイミングとイベント

ここでは、定期課金における実際の課金タイミングと生成されるイベントについて説明します。 課金の成功・失敗などの定期課金イベントは、Webhook を設定することで通知を受け取ることができます。 Webhook の詳しい仕様についてはこちらをご覧ください。

初回課金

トライアルや課金日の指定がない定期課金では、作成時に即座に課金が試行されます。 この場合、課金に成功すると定期課金は正常に作成され、課金に失敗すると定期課金は作成されません。

成功時のイベント

charge.succeeded
subscription.created

失敗時のイベント

charge.failed

トライアルなどの指定があり、課金が未来に予定されている場合、定期課金の作成のみが行われ、現在のサイクル終了日 current_period_end にセットされた日時に次回課金が実行されます。 課金が実行された場合の status は active、トライアル中の場合は trial になります。

2回目以降の課金

2回目以降の課金は、初回課金日時を基準として同日同時刻に設定されます。この日時は current_period_end で確認できます。
課金に成功するとサイクルが更新されますが、カードの有効期限切れなどで課金に失敗した場合、定期課金の status は paused になり、サイクルは停止状態になります。
また status が trial の場合、課金に成功すると active に切り替わります。

成功時のイベント

charge.succeeded
subscription.renewed

失敗時のイベント

charge.failed
subscription.paused

定期課金の再開

顧客のカードの有効期限が切れていたり、カードが不正な場合、定期課金は失敗します。このとき定期課金は停止され、再開リクエストがされるまで今後の課金は行われません。定期課金を再開するには、顧客のカードを有効なものに更新してから、再開リクエストを送信します。

curl "https://api.pay.jp/v1/subscriptions/再開する定期課金ID/resume" \
-u "sk_test_c62fade9d045b54cd76d7036": \
-XPOST

成功するとサイクルが更新され、status は active に切り替わります。

成功時のイベント

subscription.resumed
charge.succeeded(失敗課金の再開リクエスト時)

失敗時のイベント

charge.failed(失敗課金の再開リクエスト時)

課金間隔

現在 PAY.JP では、月次で1か月と年次で1年の課金サイクルをサポートしています。定期課金は月または年に一度行われます。
この課金サイクルは UTC（協定世界時）タイムゾーンを基準として計算される仕様となっており、JST（日本標準時）よりマイナス9時間を基準として計算されます。

課金日

課金日は月次のプランに任意で設定することが可能です。プランを作成するときに期間となる interval を month にして課金日となる billing_day をセットすると、その日に課金が行われるように適用されます。この場合、設定した課金日の午前 9:00 頃に課金が実行されるようになっています。 また prorate という日割りオプションを付けることで、定期課金作成時から課金日までの日割額を、作成時に課金することも可能です。 日割りについては下記のブログ記事で詳細に説明されていますのでご覧ください。

PAY.JP Engineering Blog - 定期課金日割り機能の紹介

課金日を設定しない場合は、定期課金が開始された時刻が課金日の基準となり、作成時に課金が行われます。 次回以降の課金は UTC 時刻を基準として翌月の同日同時刻に実行されます。

課金日指定の有無

プランに関しては課金日（billing_day）を指定することで、定期課金を特定の日に実行できます。

課金日(billing_day)	実行日	補足
1日	1日
31日	末日	必ず月末に実行される
30日	30日	2月28日など指定日がない場合は月末に実行され、それ以外は30日に固定される
なし	定期課金作成日	課金日を指定しない場合は、定期課金作成時に課金が行われる

課金日指定の具体例

書いてある時刻は JST（日本時間）であるとします。

プランの課金日を31に指定

• 月初開始
  • 1/1 16時頃に定期課金を作成 → 1月31日9時頃に課金 → 2月28日9時頃に課金 → 3月31日9時頃に課金
• 月末開始
  • 1/31 16時頃に定期課金を作成 → 2月28日9時頃に課金 → 3月31日9時頃に課金

プランの課金日指定なし

• 月初開始
  • 1/1 16時頃に定期課金を作成1月1日16時頃（作成時）に課金 → 2月1日16時頃に課金 → 3月1日16時頃に課金
• 月末開始
  • 1/31 16時頃に定期課金を作成1月31日16時頃（作成時）に課金 → 2月28日16時頃に課金 → 3月28日16時頃に課金

課金日の指定をしない場合の注意

月初に開始する場合

課金日なしで月初の9時以前に課金する場合、以下のようなサイクルとなります。

例： 6月1日0時頃に定期課金を作成した場合

• 日本時間（JST）: 6月1日0時頃に課金 → 7月1日0時頃に課金 → 7月31日0時頃に課金
• 弊社処理（UTC）: 5月31日15時頃に課金 → 6月30日15時頃に課金 → 7月30日15時頃に課金

このような挙動を避けたい場合、課金日の設定をしていただくか、定期課金のサイクル開始時刻を trial_end パラメーターにより9時以降にずらすなどの実装をご検討ください。

月末に開始する場合

課金日なしの定期課金は翌月に同日が存在しない場合にはもっとも近い日に課金日を移動する仕様となっております。
このため、29, 30, 31 に作成された課金日なしの定期課金は、日数が30日の月や2月を迎えるとそれ以降の実施日が前にずれていくことになります。

実際にどうなるかは、課金日指定の具体例の「プランの課金日指定なし・月末開始」をご参照ください。

日割り課金の計算

日割り課金（prorate）は定期課金の作成時、または定期課金のプラン更新時に指定できます。

• billing_day=1 prorate=True amount=1000 の定期課金を2018年8月27日に作成した場合

日割り課金(prorate)指定	課金日	時刻	計算方法
定期課金作成時	指定あり	9時(JST)前	課金額: 1000[円] ✕ 6[日] ÷ 31[日] ＝ 193[円] (端数切り捨て)
定期課金作成時	指定あり	9時(JST)後	課金額: 1000[円] ✕ 5[日] ÷ 31[日] ＝ 161[円] (端数切り捨て)

日割りの対象日数： 9時（JST）前 / 8/26〜8/31（両端日含む6日）、9時（JST）後 / 8/27〜8/31（両端日含む5日）
日割りの月の日数： 31（8月1日〜31日）
*PAYJP は内部的には UTC+0 で管理されていますので、定期課金の作成または更新の時刻が9時前後（JST）で挙動が異なります

• billing_day=1 prorate=True amount=1000 の定期課金を2018年8月27日にamount=500 のプランに変更した場合

日割り課金(prorate)指定	課金日	時刻	計算方法
定期課金プラン変更時	指定あり	9時(JST)前	課金額: 500[円] ✕ 6[日] ÷ 31[日] ＝ 96[円] (端数切り捨て)
定期課金プラン変更時	指定あり	9時(JST)後	課金額: 500[円] ✕ 5[日] ÷ 31[日] ＝ 80[円] (端数切り捨て)

定期課金のプラン変更時や削除時には残り日数分に応じた返金も同様に行われます。
また、日割り返金に関しても通常の返金と同様、期限が 180日以内 となります。
年次定期課金などを実装する際は個別振込などの対応が必要になる場合がございます為、あらかじめご注意ください。

トライアル

トライアル日数を設定すれば、無料期間を設けることができます。たとえば、30日のトライアルを設定したプランであれば、30日後に実際の課金が行われ、その日を基準として定期課金が回ります。 また稼働中の定期課金であっても、下記リクエスト例のように trial_end を指定して、リクエスト時を基準とした任意の無料期間を設けることができます。

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

これを利用して課金のタイミングを任意の日時に調整するといったことも可能です。

キャンセル

定期課金をキャンセルする場合は、以下のようなリクエストを送ることで可能です。キャンセル後、status は canceled になり、現在のサイクルの終了日である current_period_end 以降に自動で定期課金が削除されます。

curl "https://api.pay.jp/v1/subscriptions/キャンセルする定期課金ID/cancel" \
-u "sk_test_c62fade9d045b54cd76d7036": \
-XPOST

定期課金が削除される前であれば、定期課金の再開リクエストを送ることで、キャンセルを解除できます。
なお、顧客は同一プランを複数購読はできません。再度同一のプランで定期課金を行いたい場合は、定期課金を再開してください。

また、即座に定期課金を削除する場合は、以下のリクエストを送ります。

curl "https://api.pay.jp/v1/subscriptions/削除する定期課金ID" \
-u "sk_test_c62fade9d045b54cd76d7036": \
-XDELETE

削除された定期課金は、定期課金情報取得APIから情報を取得できなくなります。削除された定期課金の情報を取得したい場合は、イベント情報取得APIをご利用ください。

更新タイミングとサービス運用中の状態の扱いについて

定期課金は current_period_end を過ぎた時間以降に更新されますが、current_period_end のちょうどのタイミングで更新されるわけではありません。 定期的に更新対象をチェックし、該当の定期課金が確認できた場合に更新処理を行います。 通常時には current_period_end から大きくずれることはありませんが、多少のずれは起こり得ます。また、月初など PAY.JP 内全体で更新が集中的に重なるタイミングでは、より大きくずれる可能性があります。

定期課金を用いて自社サービスなど、登録ユーザーに対してサービスを提供している場合、更新のタイミングでのユーザーの状態の取り扱いについて注意が必要です。 上記の定期課金の仕様により、current_period_end を有料サービスの適用時間の終了日時としてしまうと、更新されるまでの時間帯にアクセスがあった場合、有料サービスを適用できない恐れがあります。

そのため、current_period_end ではなく status を見るなどの状態管理方法をおすすめします。

障害発生時の定期課金について

上流接続先による障害発生などの緊急時において、安全のため定期課金を全停止させていただくことがございます。その場合、障害発生時間帯に課金予定の定期課金が大きく遅延する可能性がありますので、ご留意ください。

障害情報についてはステータスページをご確認いただくようお願いいたします。

障害復旧後は、障害発生時間帯に停止していた定期課金がすべて実行されます。 また、障害が原因で決済に失敗してしまった定期課金も合わせて再実行されます。

• APIリファレンス - Subscription(定期課金)