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.
Before taking your integration live, review these Stripe checklists:
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.
|Customer sign-up||Make 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.|
|Invoicing||Subscriptions 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.|
|Subscription management||Set 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.|
|Trials||Offer 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.|
|Payment failures||Payments 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.|
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:
- Create a test clock
- Set up your testing simulation
- Advance the clock’s time
- Monitor and handle the changes
- 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_timeto 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:
- After creating a subscription with a seven-day free trial period, a subscription is created in a
trialingstate. 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
paidand 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.
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.
|Sent when a Customer is successfully created.|
|Sent when the subscription is created. The subscription |
|Sent when a customer’s subscription ends.|
|Sent when a subscription’s |
|Sent when a subscription previously in a |
|Sent three days before the trial period ends. If the trial is less than three days, this event is triggered.|
|Sent when a subscription starts or changes. For example, renewing a subscription, adding a coupon, applying a discount, adding an invoice item, and changing plans all trigger this event.|
|Sent when an invoice is created for a new or renewing subscription. If Stripe fails to receive a successful response to |
|Sent when an invoice is successfully finalized and ready to be paid.|
|The 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.|
|Sent when the invoice is successfully paid. You can provision access to your product when you receive this event and the subscription |
|Sent when the invoice requires customer authentication. Learn how to handle the subscription when the invoice requires action.|
A payment for an invoice failed. The PaymentIntent status changes to
|Sent 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. For existing subscriptions, changing the number of days takes effect on the next billing period. You can still add extra invoice items, if needed.|
|Sent when a payment succeeds or fails. If payment is successful the |
|Sent when a PaymentIntent is created.|
|Sent when a PaymentIntent has successfully completed payment.|
|Sent when a subscription schedule is canceled because payment delinquency terminated the related subscription.|
|Sent when a subscription schedule is canceled, which also cancels any active associated subscription.|
|Sent when all phases of a subscription schedule complete.|
|Sent when a new subscription schedule is created.|
|Sent 7 days before a subscription schedule is set to expire.|
|Sent when a subscription schedule is released, or stopped and disassociated from the subscription, which remains.|
|Sent when a subscription schedule is updated.|
Test payment failures
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
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). The subscription becomes active immediately, with a draft invoice created when the trial period ends. It takes approximately one hour for the invoice status changes to open, at which time payment collection is attempted and fails.
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
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
Test Bank Transfer payments for invoices
To test manual payments on invoices through Bank Transfer:
- Create a testmode invoice with the collection method set to
payment_settings[payment_method_types]array set to
- Find the invoice in the Dashboard and click Send.
- Your customer has been allocated a unique virtual bank account number that you can retrieve through the funding instructions API. The virtual banking details are also present in the hosted invoice page as well as the PDF.
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).
|Verification remains pending indefinitely|