更新の保留
サブスクリプションを更新すると、以下の場合に新しいインボイスが生成されます。
- トライアル期間の終了時など、サブスクリプションに初めての支払いが必要となる場合。
- 請求期間が変わった場合。
- サブスクリプションの変更で比例配分 (日割り / 秒割り計算) が発生し、
proration_behavior=always_invoice
に設定されている場合。
デフォルトでは、新しいインボイスの支払いが成功するかどうかにかかわらず、更新が適用されます。支払いが失敗した場合には、更新のロールバックは手動で実行します。新しいインボイスを作成し、そのインボイスでアイテムの比例配分を行ってから、再度支払いを開始する必要があります。ただし、更新の保留機能では、新しいインボイスの支払いが成功した場合のみに、サブスクリプションに変更を行うことができます。
注意
サブスクリプションの collection_method が send_invoice
の場合、またはサブスクリプションの決済手段として口座引き落としが使用されている場合には、更新の保留はサポートされません。
サブスクリプションを更新するサーバ側
更新の保留は、サブスクリプションの更新、サブスクリプションアイテムの作成、サブスクリプションアイテムの更新 の各コールで使用できます。更新を作成する際には、payment_behavior=pending_if_incomplete
を設定します。以下の例では、サブスクリプションに新しい料金を追加します。proration_behavior=always_invoice
が設定されているため、更新が作成されると、インボイスが作成され、支払いが試行されます。
支払いが成功すると、サブスクリプションが更新されます。支払いが失敗すると、返された Subscription
オブジェクトには、変更とともに pending_update
ハッシュが含まれます。
{ "id": "sub_49ty4767H20z6a", "object": "subscription", "application_fee_percent": null, "pending_update": { "expires_at": 1571194285, "subscription_items": [ { "id": "si_09IkI4u3ZypJUk5onGUZpe8O", "price": "price_CBb6IXqvTLXp3f" } ] }, }
失敗した支払いの処理クライアント側
更新を行った後、サブスクリプションの pending_update
ハッシュを確認します。自動通知を受け取りたい場合は、customer.subscription.updated
イベントをリッスンする Webhook を作成できます。pending_update
ハッシュが入力されている場合に、支払いが失敗すると、サブスクリプションは更新リクエストが行われなかったかのように引き続き繰り返されます。
支払い方法が拒否されたため、または顧客認証が必要なために、多くの支払いが失敗します。これらのシナリオの両方を処理するロジックを構築する必要があります。
カードの拒否を処理するには、支払いの失敗の手順を使用します。新しい支払い方法を顧客に設定してから、支払いエンドポイントを使用して、更新によって生成されたインボイスを支払う必要があります。
顧客アクションの手順を使用して、顧客認証を処理します。これにより、ユーザは認証プロセスを行ってから、インボイスを支払います。
支払いが成功すると、下記が行われます。
pending_update
ハッシュの変更をすぐに適用する。- インボイスを
paid
に更新する。
支払いが再度失敗した場合、pending_update
ハッシュは元の有効期限のままサブスクリプションに残り、変更は適用されません。