# 更新の保留 サブスクリプションの更新時に、失敗した支払いに対処する方法は以下のとおりです。 *サブスクリプション* (A Subscription represents the product details associated with the plan that your customer subscribes to. Allows you to charge the customer on a recurring basis)を更新すると、以下の場合に新しい*請求書* (Invoices are statements of amounts owed by a customer. They track the status of payments from draft through paid or otherwise finalized. Subscriptions automatically generate invoices, or you can manually create a one-off invoice)が生成されます。 - トライアル期間の終了時など、サブスクリプションに初めての支払いが必要となる場合。 - 請求期間が変わった場合。 - サブスクリプションの変更で比例配分 (日割り / 秒割り計算) が発生し、`proration_behavior=always_invoice` に設定されている場合。 多くのサブスクリプション更新では、新しい請求書が生成されたり保留中の更新がトリガーされたりすることはありません。以下に例を示します： - 構成の変更(決済手段、課税設定、再試行設定) - サブスクリプションまたはサブスクリプションアイテムのメタデータの更新 - 今後の請求書に適用されるクーポンやプロモーションコードを追加または更新 - 請求しきい値の調整 - `cancel_at_period_end` を `true` に設定する - `add_invoice_items` を使用して単発請求を追加する これらの更新は、支払いに影響することなく即時に適用されます。詳細なリストについては、[比例配分が発生しないケース](https://docs.stripe.com/billing/subscriptions/prorations.md#no-prorations)をご覧ください。 デフォルトでは、新しい請求書の支払いが成功するかどうかにかかわらず、更新が適用されます。払いが失敗した場合には、更新のロールバックは手動で実行します。新しい請求書を作成し、その請求書で項目の日割り計算を行ってから、再度支払いを開始する必要があります。ただし、更新の保留機能では、新しい請求書の支払いが成功した場合のみに、定期支払いに変更を行うことができます。 ## Before you begin サブスクリプションの [collection_method](https://docs.stripe.com/api/subscriptions/object.md#subscription_object-collection_method) が `charge_automatically` で、決済手段が次のいずれかである場合、保留中の更新を使用できます: - [Card](https://docs.stripe.com/payments/cards.md) - [Link](https://docs.stripe.com/payments/link.md) - [Alipay](https://docs.stripe.com/payments/alipay.md) - [Amazon Pay](https://docs.stripe.com/payments/amazon-pay.md) - [Afterpay/Clearpay](https://docs.stripe.com/payments/afterpay-clearpay.md) - [Apple Pay](https://docs.stripe.com/apple-pay.md) - [Cash App Pay](https://docs.stripe.com/payments/cash-app-pay.md) - [EPS](https://docs.stripe.com/payments/eps.md) - [GoPay](https://docs.stripe.com/payments/gopay.md) - [Google Pay](https://docs.stripe.com/google-pay.md) - [Kakao Pay](https://docs.stripe.com/payments/kakao-pay/accept-a-payment.md) - [Klarna](https://docs.stripe.com/payments/klarna.md) - [KR Card](https://docs.stripe.com/payments/kr-card/accept-a-payment.md) - [Naver Pay](https://docs.stripe.com/payments/naver-pay/accept-a-payment.md) - [NG Card](https://docs.stripe.com/payments/ng-card/accept-a-payment.md) - [PayPal](https://docs.stripe.com/payments/paypal.md) - [PayTo](https://docs.stripe.com/payments/payto.md) - [Pix](https://docs.stripe.com/payments/pix.md) - [PromptPay](https://docs.stripe.com/payments/promptpay.md) - [Revolut Pay](https://docs.stripe.com/payments/revolut-pay.md) - [Satispay](https://docs.stripe.com/payments/satispay.md) - [ステーブルコインおよび暗号資産](https://docs.stripe.com/payments/stablecoin-payments.md) - [Swish](https://docs.stripe.com/payments/swish.md) - [TWINT](https://docs.stripe.com/payments/twint.md) - [UPI](https://docs.stripe.com/payments/upi.md) - [WeChat Pay](https://docs.stripe.com/payments/wechat-pay.md) ## サブスクリプションを更新する [サーバ側] 更新の保留は、[サブスクリプションの更新](https://docs.stripe.com/api/subscriptions/update.md)、[サブスクリプションアイテムの作成](https://docs.stripe.com/api/subscription_items/create.md)、[サブスクリプションアイテムの更新](https://docs.stripe.com/api/subscription_items/update.md)の各コールで使用できます。更新を作成する際には、`payment_behavior=pending_if_incomplete` を設定します。以下の例では、サブスクリプションに新しい料金を追加しています。`proration_behavior=always_invoice` が設定されているため、更新が作成されると、請求書が作成されて支払いが試行されます。 #### curl ```bash curl https://api.stripe.com/v1/subscriptions/sub_49ty4767H20z6a \ -u <>: \ -d "payment_behavior"="pending_if_incomplete" \ -d "proration_behavior"="always_invoice" \ -d "items[0][id]"="si_09IkI4u3ZypJUk5onGUZpe8O" \ -d "items[0][price]"="price_CBb6IXqvTLXp3f" ``` 支払いが成功すると、サブスクリプションが更新されます。支払いが失敗すると、返された `Subscription` オブジェクトには、変更とともに `pending_update` ハッシュが含まれます。 ```json { "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* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) で `customer.subscription.updated` イベントをリッスンします。`pending_update` ハッシュが入力されている場合、支払いが失敗し、サブスクリプションの更新は適用されていないことを示します。 カードの支払い拒否と顧客認証リクエストに起因する支払い失敗を処理するロジックを構築します。 - カードが支払い拒否された場合は、顧客に[新しい決済手段を関連付け](https://docs.stripe.com/billing/subscriptions/overview.md#requires-payment-method)ます。その後、[pay (支払う)](https://docs.stripe.com/api/invoices/pay.md) エンドポイントを使用して、更新によって生成された請求書を支払います。 - 顧客認証については、[要対応](https://docs.stripe.com/billing/subscriptions/overview.md#requires-action)のフローに従います。 支払いが成功すると、すぐに `pending_update` ハッシュの変更が適用され、請求書が `paid` に更新されます。 支払いが再度失敗した場合、`pending_update` ハッシュは元の[有効期限](https://docs.stripe.com/billing/subscriptions/pending-updates.md#expiration)のままサブスクリプションに残り、変更も適用されません。 ## Optional: 保留中の更新をキャンセルまたは変更する [サーバ側] 保留されている更新をキャンセルするには、更新で作成された請求書を無効にする必要があります。サブスクリプションの [latest invoice](https://docs.stripe.com/api/subscriptions/object.md#subscription_object-latest_invoice) 属性を確認して、請求書 ID を調べます。次にその ID を使用して請求書を[無効](https://docs.stripe.com/api/invoices/void.md)にします。 保留中の更新の新しい値で[サブスクリプションを更新](https://docs.stripe.com/billing/subscriptions/pending-updates.md#update-subscription)できます。これにより、`pending_update` ハッシュの値が更新され、前回の保留中の更新に関連付けられた請求書が無効になり、更新された値を反映する新しい請求書が作成されます。この新しい請求書の支払いが成功すると、サブスクリプションに最新の更新が適用されます。支払いが失敗すると、既存の更新を置き換える[有効期限](https://docs.stripe.com/billing/subscriptions/pending-updates.md#expiration)が設定された新しい保留中の更新が生成されます。 ## 保留中の更新でサポートされる属性 保留中の更新は、比例配分の動作を制御したり、新しい請求書を生成したりする属性のみをサポートします。 [update subscription (サブスクリプションの更新)](https://docs.stripe.com/api/subscriptions/update.md) エンドポイントは、次の属性をサポートしています。 - `expand` - `payment_behavior` - `proration_behavior` - `proration_date` - `billing_cycle_anchor` - `items` - `price` - `quantity` - `trial_end` - `trial_from_plan` - `add_invoice_items` [create subscription item (サブスクリプション項目の作成)](https://docs.stripe.com/api/subscription_items/create.md) エンドポイントと [update subscription item (サブスクリプション項目の更新)](https://docs.stripe.com/api/subscription_items/update.md) エンドポイントは、次の属性をサポートしています。 - `expand` - `payment_behavior` - `proration_behavior` - `proration_date` - `price` - `quantity` ## 期限切れの更新 更新が失敗した後にアクションを実行しなかった場合、Stripe は請求書を無効にし、有効期限が切れた後に更新を破棄します。 保留中の更新の `expired_at` の時刻は、[トライアル終了時](https://docs.stripe.com/api/subscriptions/object.md#subscription_object-trial_end)または最も早い [items.current 期間の終了時](https://docs.stripe.com/api/subscriptions/object.md##subscription_object-items-data-current_period_end)のいずれか早い時刻と一致します。これは、時刻が更新リクエストから 23 時間以内である場合に適用されます。それ以外の場合、有効期限は更新リクエストから 23 時間です。 さらに以下のいずれかが発生した場合には、 Stripe は請求書を自動的に無効化し、更新の保留を削除します。 - サブスクリプションが請求のしきい値に達した。 - サブスクリプションにリンクされたサブスクリプションのスケジュールが新しいフェーズに移行した。 ## 更新の保留イベント [Webhook](https://docs.stripe.com/webhooks.md) を使用して、保留中の更新に関連する次のイベントを監視します。`Customer` オブジェクトと顧客設定の `Account` オブジェクトのどちらを使用する場合も、イベントは同じです。 | イベント | 目的 | | ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `customer.subscription.updated` | サブスクリプションの通知を受け取ります。`pending_updates` ハッシュを確認し、必要に応じて[支払いの失敗を解決](https://docs.stripe.com/billing/subscriptions/pending-updates.md#handling-failed-payments)します。 | | `customer.subscription.pending_update_applied` | アップグレード、ダウングレード、プロビジョニング、プロビジョニングサービスなどの追加アクションを取れるように、保留中の更新が適用された場合に通知を受け取ります。 | | `customer.subscription.pending_update_expired` | 更新の保留の期限が切れたり、自動的に無効化されると通知を受け取ります。必要に応じて、更新リクエストを再試行してください。 | ## 更新の保留とサブスクリプションのスケジュール 更新の保留と[サブスクリプションスケジュール](https://docs.stripe.com/billing/subscriptions/subscription-schedules.md)の両方を使用して、サブスクリプションを管理できます。スケジュールフェーズを変更すると、保留されている更新が破棄され、関連する請求書が無効になります。必要に応じて、フェーズ移行後に更新リクエストを再試行してください。 ## 従量制項目 サブスクリプションにメーター項目が含まれる場合、Stripe は未払いの使用状況を保留中の更新の請求書で請求を行います。ただし、保留中の更新が支払い前に期限切れになった場合、Stripe はこの使用状況を破棄します。それ以降の請求書でその記録に対する請求は行われなくなります。 保留中の更新によって従量料金が削除された場合、Stripe は保留中の更新の作成とその結果生じる請求書の支払いの間に報告された使用量をすべて無視します。その使用量に対して請求することはできません。ただし、サブスクリプションに `billing_mode=flexible` が指定されている場合、従量制料金を削除すると、使用量に対して請求が行われます。