更新の保留

サブスクリプションの更新時に、失敗した支払いに対処する方法は以下のとおりです。

サブスクリプションを更新すると、以下の場合に新しい請求書が生成されます。

トライアル期間の終了時など、サブスクリプションに初めての支払いが必要となる場合。
請求期間が変わった場合。
サブスクリプションの変更で比例配分 (日割り / 秒割り計算) が発生し、proration_behavior=always_invoice に設定されている場合。

デフォルトでは、新しい請求書の支払いが成功するかどうかにかかわらず、更新が適用されます。払いが失敗した場合には、更新のロールバックは手動で実行します。新しい請求書を作成し、その請求書で項目の日割り計算を行ってから、再度支払いを開始する必要があります。ただし、更新の保留機能では、新しい請求書の支払いが成功した場合のみに、定期支払いに変更を行うことができます。

はじめに

サブスクリプションの collection_method が charge_automatically の場合、またはサブスクリプションの決済手段がカードまたは Link の場合、保留中の更新を使用できます。

サブスクリプションを更新する
サーバ側

更新の保留は、サブスクリプションの更新、サブスクリプションアイテムの作成、サブスクリプションアイテムの更新の各コールで使用できます。更新を作成する際には、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 ハッシュを確認するか、Webhook で customer.subscription.updated イベントをリッスンします。pending_update ハッシュが入力されている場合、支払いが失敗し、サブスクリプションの更新は適用されていないことを示します。

カードの支払い拒否と顧客認証リクエストに起因する支払い失敗を処理するロジックを構築します。

カードが支払い拒否された場合は、顧客に新しい決済手段を関連付けます。その後、pay (支払う) エンドポイントを使用して、更新によって生成された請求書を支払います。
顧客認証については、要対応のフローに従います。

支払いが成功すると、すぐに pending_update ハッシュの変更が適用され、請求書が paid に更新されます。

支払いが再度失敗した場合、pending_update ハッシュは元の有効期限のままサブスクリプションに残り、変更も適用されません。

オプション保留中の更新をキャンセルまたは変更する
サーバ側

保留中の更新でサポートされる属性

保留中の更新は、比例配分の動作を制御したり、新しい請求書を生成したりする属性のみをサポートします。

update subscription (サブスクリプションの更新) エンドポイントは、次の属性をサポートしています。

expand
payment_behavior
proration_behavior
proration_date
billing_cycle_anchor
items
- price
- quantity
trial_end
trial_from_plan
add_invoice_items

create subscription item (サブスクリプション項目の作成) エンドポイントと update subscription item (サブスクリプション項目の更新) エンドポイントは、次の属性をサポートしています。

expand
payment_behavior
proration_behavior
proration_date
price
quantity

期限切れの更新

更新が失敗した後にアクションを実行しなかった場合、Stripe は請求書を無効にし、有効期限が切れた後に更新を破棄します。

保留中の更新の expired_at の時刻は、トライアル終了時または最も早い items.current 期間の終了時のいずれか早い時刻と一致します。これは、時刻が更新リクエストから 23 時間以内である場合に適用されます。それ以外の場合、有効期限は更新リクエストから 23 時間です。

さらに以下のいずれかが発生した場合には、 Stripe は請求書を自動的に無効化し、更新の保留を削除します。

サブスクリプションが請求のしきい値に達した。
サブスクリプションにリンクされたサブスクリプションのスケジュールが新しいフェーズに移行した。