Testing Stripe Billing

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, development checklists, etc) to help determine whether your integration is production-ready.

Test clocks

One of the easiest ways to test your integration is to use 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.

Go-live principles

Before taking your integration live, review these Stripe checklists:

• Account checklist
• Development checklist
• Website checklist

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

• Payment collection — Can your integration successfully collect customer payment information, whether you used Checkout or Elements?
• Invoices — Can your integration create and pay invoices?
• Subscription management — Can your integration create, modify, and cancel subscriptions?
• Failed payments — Can your integration handle and retry failed payments?
• Webhooks - Is your integration listening to the right event notifications and handling them correctly?
• Other scenarios — Can your integration handle credit notes, refunds, and disputes?

Testing subscription trial periods

You can test how your integration handles trial periods without waiting a full trial period to see the results by creating a new subscription with a trial_end value a few minutes in the future.

Using this approach, you won’t see a customer.subscription.trial_will_end event notification (which occurs three days before a trial ends), but in all other ways it behaves the same as a subscription with a longer trial period.

Testing subscription webhook notifications

Using subscriptions relies heavily on webhooks. 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. By using the Stripe CLI instead of the Dashboard to trigger events, you can see event notifications on your server as they come in. This means you can check your webhook integration directly without complicating factors such as network tunnels or firewalls.

When you use either 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.

Testing 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).

Depending on your retry settings, you’ll have to wait a day or more to see the first retry attempt. If required, you can use that period to update the customer’s payment method to a working test card to see what happens for a successful retry.

Testing 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.

Testing 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.

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

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

Testing customer tax ID verification

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