Testing Stripe Billing

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.

Test clocks

Test clocks allow you to simulate Billing objects, like subscriptions, through time in a sandbox 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 4242424242424242
  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 trialing status. 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 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.

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). 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 a sandbox, which causes Billing resources, like Subscriptions, to change status 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 0027 6000 3184 card to simulate 3D Secure triggering for subscriptions and invoices.

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 Bank Transfer payments for invoices

To test manual payments on invoices through Bank Transfer:

1. In a sandbox, create an invoice and set the collection method to send_invoice and set the payment_settings[payment_method_types] array to [customer_balance].
2. Find the invoice in the Dashboard and click Send.
3. 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 the default payment method for invoices and subscriptions

Use specific test card IDs to simulate default payment methods being used for subscriptions and invoices.

The provided payment method must be attached to the subscription or invoice’s customer setting it as the default_payment method. For example, if using pm_card_visa to create a test Visa payment method:

1. Call the PaymentMethod Attach endpoint with pm_card_visa and the intended customer for the subscription or invoice
2. With the resulting Payment Method ID, create the subscription or invoice with this ID as the default_payment_method.

Now, the subscription or invoice will charge this payment method.

Learn more about using default payment methods for subscriptions and invoices.

Test customer tax ID verification

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

Automated testing

You can set up automated testing for your integration. To optimize the testing:

• Be aware of the data retention policy for subscription-related data in a sandbox.
• Avoid re-using resources like Coupons and Promotion Codes across tests.
• Use the stripe-mock HTTP server, which is based on the Stripe API and closely reflects the API’s behavior.