定期課金

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 pamount=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(定期課金)