定期課金

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"

顧客を登録して定期課金を行う

次に実際に定期課金を行うために、課金の対象となる顧客を作成します。クレジットカード課金なので、カード情報の紐付いた顧客である必要があります。

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

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

{
  "cards": {
    "count": 1,
    "data": [
      {
        "address_city": null,
        "address_line1": null,
        "address_line2": null,
        "address_state": null,
        "address_zip": null,
        "address_zip_check": "unchecked",
        "brand": "Visa",
        "country": null,
        "created": 1441537780,
        "customer": "cus_2849e3adb18f8997760001007bbd",
        "cvc_check": "passed",
        "exp_month": 12,
        "exp_year": 2020,
        "fingerprint": "e1d8225886e3a7211127df751c86787f",
        "id": "car_d9024617c1aa88e611b994610825",
        "last4": "4242",
        "name": null,
        "object": "card"
      }
    ],
    "has_more": false,
    "object": "list",
    "url": "/v1/customers/cus_2849e3adb18f8997760001007bbd/cards"
  },
  "created": 1441537780,
  "default_card": "car_d9024617c1aa88e611b994610825",
  "description": null,
  "email": "subscriber@pay.jp",
  "id": "cus_2849e3adb18f8997760001007bbd",
  "livemode": false,
  "object": "customer",
  "subscriptions": {
    "count": 0,
    "data": [],
    "has_more": false,
    "object": "list",
    "url": "/v1/customers/cus_2849e3adb18f8997760001007bbd/subscriptions"
  }
}

ここでかえってきた顧客ID cus_2849e3adb18f8997760001007bbd と課金を行いたいプランを紐付けて、定期課金リクエストを行います。

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

定期課金は、後述する課金日の指定やトライアルを指定することで、課金を任意のタイミングで行うことができます。 今回の例で作成したプランは、課金日やトライアルの指定がないため、定期課金を作成したタイミングで即座に課金が試行されています。

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

ここでは定期課金で実際に課金が行われるタイミングや生成されるイベントについて説明します。 課金が成功したかどうかなど定期課金のイベントは、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年の課金サイクルをサポートしています。定期課金は月または年に一度行われ、月末を基準とした定期課金( billing_day が指定されたプラン)の場合は、確実に月末に課金が回るようになっています。例えば、月末に月次の定期課金が行われた場合、1月31日に課金 => 2月28日に課金 => 3月31日に課金というように、確実に月末に課金が回るようなしくみとなっています。

課金日

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

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

課金日を設定しない場合は、定期課金が始まった日が課金日の基準となり、時間もその時間を目安に課金が行われます。

トライアル

トライアル日数を設定すれば、無料期間を設けることができます。例えば、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リファレンス - Subscription(定期課金)