Handle subscriptions with deferred payment

無料トライアルや従量課金を含むサブスクリプション、またはクーポンや顧客のクレジット残高が適用された請求書は、未払いになることがよくあります。これは、サブスクリプションの作成時に顧客にすぐに請求を行わないことが原因です。

Although you don’t charge customers for the first invoice, authenticating and authorizing their card can help increase successful completion of the first non-zero payment. These types of payments are known as off-session payments. To manage these scenarios, Stripe uses SetupIntents.

SetupIntents を使用する

You can use SetupIntents to:

• 決済情報を収集します。
• Authenticate your customer’s card to claim exemptions later.
• Authorize your customer’s card without charging it.

決済を認証すると、顧客はカードへの請求を許可できます。これは強力な顧客認証での要求事項であり、3DS はこの認証を完了するため方法として一般的です。支払い方法情報を収集してオーソリすることにより、その支払い方法への請求が確実に成功するようになります。

In off-session scenarios, SetupIntents enable you to charge customers for their first non-zero payment without having to return them to your website or app for authentication. This reduces friction for your customers.

Stripe automatically creates SetupIntents for subscriptions that don’t require an initial payment. The authentication and authorization process also completes at this point, if required. If both succeed or aren’t required, no action is necessary, and the subscription.pending_setup_intent field is null. If either step fails, Stripe recommends using the SetupIntent on your front end to resolve the issue while your customer is on-session.

The pending_setup_intent field on a subscription doesn’t cancel automatically when the subscription ends. Listen for customer.subscription.deleted events and manually cancel a subscription SetupIntent if needed.

The next two sections explain how to manage scenarios where authentication or authorization fail.

認証の失敗の管理Client-side

認証の失敗は、Stripe が顧客のカード発行会社との間で顧客を認証できない場合に発生します。この場合、SetupIntent の status が requires_action に設定されます。

To resolve these scenarios, call confirmCardSetup on your front end so your customer can complete the authentication flow manually. The code example below expands the pending_setup_intent to complete the flow.

const {pending_setup_intent} = subscription;

if (pending_setup_intent) {
  const {client_secret, status} = subscription.pending_setup_intent;

  if (status === "requires_action") {
    const {setupIntent, error} = await stripe.confirmCardSetup(client_secret);

    if (error) {
      // Display error.message in your UI.
    } else {
      // The setup has succeeded. Display a success message.
    }
  }
}

After completing this flow, authorization executes if it’s required. If authorization succeeds, or if it’s not required, pending_setup_intent is updated to null upon completion.

オーソリの失敗の管理Client-side

Payment authorization failures occur when Stripe can’t verify that a card can be charged. This sets the status of the SetupIntent to requires_payment_method, which usually means that subsequent charges with that card fail.

To resolve these scenarios, collect a new payment method, then update the default payment method for your customer or the subscription. The code example below expands the pending_setup_intent to complete the flow.

const {pending_setup_intent, latest_invoice} = subscription;

if (pending_setup_intent) {
  const {client_secret, status} = subscription.pending_setup_intent;

  if (status === "requires_action") {
    const {setupIntent, error} = await stripe.confirmCardSetup(client_secret);

    if (error) {
      // Display error.message in your UI.
    } else {
      // The setup has succeeded. Display a success message.
    }
  } else if (status === "requires_payment_method") {
    // Collect new payment method.
  }
}