Skip to content
Create account
or
Sign in
The Stripe Docs logo
/
Ask AI
Create account
Sign in
Get started
Payments
Revenue
Platforms and marketplaces
Money management
Developer resources
Overview
Billing
OverviewAbout the Billing APIs
Subscriptions
    Overview
    How subscriptions work
    Get started
    Quickstart
    Plan an integration
    Build an integration
    Use cases
    About subscriptions
    Enable billing mode
    Subscription event definitions
    Entitlements
    Subscription invoices
    Subscription schedules
    Recurring pricing models
    Strong Customer Authentication (SCA)
    Set up subscriptions
    Configure collection methods
    Embed a pricing table
    Set quantities
    Set billing cycles
    Manage subscriptions
    Migrate subscriptions to Stripe
    Subscribe to multiple items
    Backdate subscriptions
    Set trial periods
    Handle subscriptions with deferred payment
    Apply coupons
    Modify subscriptions
    Manage subscription payment methods
    Analytics
Invoicing
Usage-based billing
Quotes
Customer management
Billing with other products
Revenue recovery
Automations
Test your integration
Tax
Overview
Use Stripe tax
Manage compliance
Reporting
Overview
Select a report
Configure reports
Reports API
Reports for multiple accounts
Revenue recognition
Data
OverviewSchema
Custom reports
Data Pipeline
Data management
HomeRevenueSubscriptions

Handle subscriptions with deferred payment

Learn how to handle subscriptions that don't require immediate payment.

Subscriptions that include free trials, usage-based billing, invoices with coupons, or applied customer credit balances often result in non-payment invoices. This means you don’t immediately charge your customer when you create the subscription.

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.

Use SetupIntents

You can use SetupIntents to:

  • Collect payment information.
  • Authenticate your customer’s card to claim exemptions later.
  • Authorize your customer’s card without charging it.

Authenticating payments allows your customer to grant permissions to charge their card. Strong Customer Authentication requires this, and 3DS is a common way to complete it. Collecting payment method information and authorizing it ensures that you can successfully charge the payment method.

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.

Manage authentication failures Client-side

Authentication failures occur when Stripe is unable to authenticate your customer with their card issuer. When this happens, the status of the SetupIntent is set to requires_action.

How to handle subscription payment authentication failures.

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.

Manage authorization failures 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.

How to handle subscription payment authorization failures.

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. } }
Was this page helpful?
YesNo
  • Need help? Contact Support.
  • Join our early access program.
  • Check out our changelog.
  • Questions? Contact Sales.
  • LLM? Read llms.txt.
  • Powered by Markdoc