Skip to content
Sign in
An image of the Stripe logo
Create account
Sign in
Home
Payments
Finance automation
Banking as a service
Developer tools
No-code
All products
Home
Payments
Finance automation
Home
Payments
Finance automation
Banking as a service
Developer tools
Overview
Billing
    Overview
    Subscriptions
    Invoicing
    Quotes
    Collection methods
    Manage recurring revenue
    Products and prices
    Customer management
    About the Billing APIs
    Test your integration
      Test clocks
      Test your invoicing integration
    Strong Customer Authentication (SCA)
    Invoices API updates
Tax
Reporting
Data
Startup incorporation
Account
HomeFinance automationBilling

Testing Stripe Billing

Learn how to test your Billing integration.

Testing resources

  • Use test cards to trigger different scenarios, like payment failures or required authentication.
  • Use test clocks to simulate Billing objects through time and test events at different milestones, like the end of a free trial or annual plan.
  • Read the general testing doc to learn about fundamental testing common to all of Stripe.

You should thoroughly test your integration before you expose it to customers or use it for any live activity. Use the resources on this page in addition to any organizational guidelines (for example, runbooks, quality gates, or development checklists) to help determine whether your integration is production-ready.

Go-live principles

Before taking your integration live, review these Stripe checklists:

  • Account checklist
  • Development checklist
  • Website checklist

Here’s what a typical integration flow looks like.

For subscription and recurring revenue integrations, make sure that, at a minimum, the following components work as expected.

The table lists the event notifications for each component. You can configure your integration to listen for these events with webhooks. Read this guide to learn more about event notifications and testing.

ComponentDescriptionEvents
Customer sign-upMake sure your integration can successfully collect the information you need to create a Customer record in Stripe. Your customers can enter that information through Payment Links Checkout, Elements, or a completely custom payment form built with the Stripe API. No matter which form you use, make sure that you see the Customer object stored on Stripe. You can use the Dashboard or API to view and manage Customers.
  • customer.created
  • customer.subscription.created
InvoicingSubscriptions generate Invoices at the end of each billing cycle. Depending on your payment collection method, you may send an invoice to collect payment in arears or to confirm an automatic charge. Make sure that your integration creates and sends invoices as you expect. Read the guide to learn more about creating and managing invoices for subscriptions. You can use test clocks to simulate billing cycles, which include generating and sending invoices. Read the test clocks guide to learn about specific use cases to test.
  • invoice.created
  • invoice.finalized
  • invoice.finalization_failed
  • invoice.paid
  • invoice.payment_action_required
  • invoice.payment_failed
  • invoice.upcoming
  • invoice.updated
Subscription managementSet up the customer portal to let your customers manage their subscriptions and billing information. To test it, create a subscription in test mode. Then, log in to the portal as the test user and update the subscription. Check the Dashboard or API to see whether the subscription reflects the customer’s change. Read the integration guide to learn how to set up the customer portal.
  • customer.subscription.deleted
  • customer.subscription.paused
  • customer.subscription.resumed
  • customer.subscription.updated
TrialsOffer customers a trial of your service. To test that your trial is set up correctly, you can create a test clock. The subscription should generate a zero-value invoice for the trial period. Learn how to test trials with test clocks. For more information about how trials work, read the subscription trials guide.
  • customer.subscription.trial_will_end
  • customer.subscription.updated
Payment failuresPayments from your customers may fail for a number of reasons. Make sure your integration can handle failures, including retrying payments. Learn how to test payment failures.
  • invoice.finalization_failed
  • invoice.payment_failed
  • invoice.payment_action_required

Test clocks

Test clocks allow you to simulate Billing objects, like subscriptions, through time in test mode so you don’t have to wait a year to see how your integration handles a payment failure for an annual renewal. You don’t need to write any code with test clocks: you can create simulations in the Dashboard. You can also access them through the API. Learn more about test clocks and common use cases for them.

Test subscription trial periods

First, follow these steps to start using test clocks:

  1. Create a test clock
  2. Set up your testing simulation
  3. Advance the clock’s time
  4. Monitor and handle the changes
  5. Update the simulation

Next, you can start testing trials with test clocks. Let’s say that you want customers to try your product for free with a seven-day trial before they start paying and want to collect payment information up front. To simulate this situation using test clocks, follow these steps:

  • Create a new test clock and set its frozen_time to January 1.
  • Add a customer and include their payment method. In this case, use a test card.
  • Create a subscription and add a seven-day free trial period:

To add a trial period to an existing subscription using the Dashboard:

Find the subscription you want to change.

  1. Click Actions.
  2. Click Update subscription.
  3. Click Add free trial and enter seven in Free trial days field.
  4. Click Update subscription.
  • After creating a subscription with a seven-day free trial period, a subscription is created in a trialing state. An invoice of $0.00 is generated due to the free trial.
  • Advance the date to January 5 to see the customer.subscription.trial_will_end event notification. Stripe sends the notification three days before the trial ends. You can use this webhook event to inform your customers that the trial ends soon.
  • Advance the date to January 8 to see that the subscription is now paid and an invoice for 50 USD is created.
  • Advance the date by one cycle (for example, to February 8 for a monthly subscription) to see the subscription renew successfully.

Test trial periods without test clocks

Test subscription webhook notifications

Subscriptions integrations rely heavily on webhooks. You set up a webhook endpoint on your server and specify which event notifications to listen for. Stripe emits notifications for events like a subscription upgrade or cancellation.

You can test webhooks by either creating actual test subscriptions or by triggering event notifications with the Stripe CLI or through the Dashboard.

After you set up the Stripe CLI and link to your Stripe account, you can trigger events from the subscription lifecycle to test your webhook integration. If you use the Stripe CLI to trigger events, you can see event notifications on your server as they come in, which allows you to check your webhook integration directly without network tunnels or firewalls.

When you use the Stripe CLI or the Dashboard to trigger events, the event your webhook receives contains fake data that doesn’t correlate to subscription information. The most reliable way to test webhook notifications is to create actual test subscriptions and handle the corresponding events.

The following table describes the most common events related to subscriptions and, where applicable, suggests actions for handling the events.

Event

Description

customer.createdSent when a Customer is successfully created.
customer.subscription.createdSent when the subscription is created. The subscription status might be incomplete if customer authentication is required to complete the payment or if you set payment_behavior to default_incomplete. View subscription payment behavior to learn more.
customer.subscription.deletedSent when a customer’s subscription ends.
customer.subscription.pausedSent when a subscription’s status changes to paused. For example, this is sent when a subscription is configured to pause when a free trial ends without a payment method. Invoicing won’t occur until the subscription is resumed. We don’t send this event if payment collection is paused because invoices continue to be created during that time period.
customer.subscription.resumedSent when a subscription previously in a paused status is resumed. This doesn’t apply when payment collection is unpaused.
customer.subscription.trial_will_endSent three days before the trial period ends. If the trial is less than three days, this event is triggered.
customer.subscription.updatedSent when the subscription is successfully started, after the payment is confirmed. Also sent whenever a subscription is changed. For example, adding a coupon, applying a discount, adding an invoice item, and changing plans all trigger this event.
invoice.createdSent when an invoice is created for a new or renewing subscription. If Stripe fails to receive a successful response to invoice.created, then finalizing all invoices with automatic collection is delayed for up to 72 hours. Read more about finalizing invoices.
  • Respond to the notification by sending a request to the Finalize an invoice API.
invoice.finalizedSent when an invoice is successfully finalized and ready to be paid.
  • You can send the invoice to the customer. View invoice finalization to learn more.
  • Depending on your settings, we automatically charge the default payment method or attempt collection. View emails after finalization to learn more.
invoice.finalization_failedThe invoice couldn’t be finalized. Learn how to handle invoice finalization failures by reading the guide. Learn more about invoice finalization in the invoices overview guide.
  • Inspect the Invoice’s last_finalization_error to determine the cause of the error.
  • If you’re using Stripe Tax, check the Invoice object’s automatic_tax field.
  • If automatic_tax[status]=requires_location_inputs, the invoice can’t be finalized and payments can’t be collected. Notify your customer and collect the required customer location.
  • If automatic_tax[status]=failed, retry the request later.
invoice.paidSent when the invoice is successfully paid. You can provision access to your product when you receive this event and the subscription status is active.
invoice.payment_action_requiredSent when the invoice requires customer authentication. Learn how to handle the subscription when the invoice requires action.

invoice.payment_failed

A payment for an invoice failed. The PaymentIntent status changes to requires_action. The status of the subscription continues to be incomplete only for the subscription’s first invoice. If a payment fails, there are several possible actions to take:

  • Notify the customer. Read about how you can configure subscription settings to enable Smart Retries and other revenue recovery features.
  • If you’re using PaymentIntents, collect new payment information and confirm the PaymentIntent.
  • Update the default payment method on the subscription.
invoice.upcomingSent a few days prior to the renewal of the subscription. The number of days is based on the number set for Upcoming renewal events in the Dashboard. You can still add extra invoice items, if needed.
invoice.updatedSent when a payment succeeds or fails. If payment is successful the paid attribute is set to true and the status is paid. If payment fails, paid is set to false and the status remains open. Payment failures also trigger a invoice.payment_failed event.
payment_intent.createdSent when a PaymentIntent is created.
payment_intent.succeededSent when a PaymentIntent has successfully completed payment.

Test payment failures

Use specific test credit card numbers to trigger payment failures for subscriptions and invoices.

Some subscription updates cause Stripe to invoice the subscription and attempt payment immediately (this synchronous payment attempt can occur on the initial invoice, or on certain invoice updates). If this attempt fails, the subscription is created in an incomplete status.

To test the effects of payment failure on an active subscription, attach the 4000 0000 0000 0341 card as the customer’s default payment method, but use a trial period to defer the attempt (a trial of a few seconds or minutes is sufficient).

Use test clocks to simulate the forward movement of time in test mode, which causes Billing resources, like Subscriptions, to change state and trigger webhook events. This allows you to see how your integration handles a payment failure for a quarterly or annual renewal without waiting a year.

Test payments that require 3D Secure

Use the 4000 0000 0000 3063 card to simulate 3D Secure triggering for subscriptions and invoices. You can also write custom Radar rules in testmode to trigger authentication.

When a 3D Secure authentication flow is triggered, you can test authenticating or failing the payment attempt in the 3DS dialog that opens. If the payment is authenticated successfully, the invoice is paid. If the invoice belongs to a subscription in an incomplete status, the subscription becomes active. When a payment attempt fails, the authentication attempt is unsuccessful and the invoice remains open.

Test ACH credit transfer payments for invoices

To test manual payments on invoices through ACH credit transfers:

  1. Create a testmode invoice with the collection method set to send_invoice.
  2. Find the invoice in the Dashboard and click Send.
  3. Identify the newly-created ach_credit_transfer source on the customer being invoiced.
  4. Update the owner email to amount_XXXX@any_domain.com, where XXXX is an integer representing the amount of money transferred. For example, to transfer 149.35 USD, set the email to amount_14935@example.com.

Caution

You don’t need to create the ACH credit transfer source. Where applicable, Stripe dynamically creates the source as part of the invoicing workflow.

Here’s how to update the email on the created source:

Command Line
curl https://api.stripe.com/v1/sources/src_19Q3AILlRB0eXbMt81RVDnM9 \ -u "
sk_test_4eC39HqLyjWDarjtT1zdp7dc
:"
\ --data-urlencode "owner[email]"="amount_1000@example.com"

Test customer tax ID verification

Use these magic tax IDs to trigger certain verification conditions in test mode. The tax ID type must be either the EU VAT Number or Australian Business Number (ABN).

NumberType
000000000Successful verification
111111111Unsuccessful verification
222222222Verification remains pending indefinitely
Was this page helpful?
Need help? Contact Support.
Watch our developer tutorials.
Check out our product changelog.
Questions? Contact Sales.
Powered by Markdoc
You can unsubscribe at any time. Read our privacy policy.
On this page
Go-live principles
Test clocks
Test subscription trial periods
Test subscription webhook notifications
Test payment failures
Test payments that require 3D Secure
Test ACH credit transfer payments for invoices
Test customer tax ID verification
Stripe Shell
Test mode
Welcome to the Stripe Shell! Stripe Shell is a browser-based shell with the Stripe CLI pre-installed. Login to your Stripe account and press Control + Backtick on your keyboard to start managing your Stripe resources in test mode. - View supported Stripe commands: - Find webhook events: - Listen for webhook events: - Call Stripe APIs: stripe [api resource] [operation] (e.g. )
The Stripe Shell is best experienced on desktop.
$