# Test your Billing integration Learn how to test your Billing integration to make sure it's ready for production. - Use test [cards](https://docs.stripe.com/testing.md#cards) and [account numbers](https://docs.stripe.com/testing.md#test-account-numbers) to trigger different scenarios, such as payment failures or required authentication. - Use [test clocks](https://docs.stripe.com/billing/testing/test-clocks.md) to simulate Billing objects through time and test events at different milestones, such as the end of a free trial or annual plan. - Read the [general testing doc](https://docs.stripe.com/testing.md) to learn about fundamental testing common to all of Stripe. 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 organisational 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](https://docs.stripe.com/get-started/account/checklist.md) - [Development checklist](https://docs.stripe.com/get-started/checklist/go-live.md) - [Website checklist](https://docs.stripe.com/get-started/checklist/website.md) Here’s what a typical integration flow looks like. A basic Billing integration (See full diagram at https://docs.stripe.com/billing/testing) If your Connect platform uses [customer-configured Accounts](https://docs.stripe.com/api/v2/core/accounts/create.md#v2_create_accounts-configuration-customer), use our [guide](https://docs.stripe.com/connect/use-accounts-as-customers.md) to replace `Customer` and event references in your code with the equivalent Accounts v2 API references. 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 *webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests)s. Read this guide to learn more about [event notifications](https://docs.stripe.com/billing/testing.md#webhooks) and testing. | Component | Description | Events | | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **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* (A set of UI components for building a web checkout flow. They adapt to your customer's locale, validate input, and use tokenization, keeping sensitive customer data from touching your server), or a completely custom payment form built with the [Stripe API](https://docs.stripe.com/api.md). 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](https://docs.stripe.com/billing/customer.md#manage-customers). | - `customer.created` - `customer.subscription.created` | | **Invoicing** | Subscriptions generate *Invoices* (Invoices are statements of amounts owed by a customer. They track the status of payments from draft through paid or otherwise finalized. Subscriptions automatically generate invoices, or you can manually create a one-off invoice) at the end of each billing period. Depending on your payment collection method, you can send an invoice to collect payment in arrears 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](https://docs.stripe.com/billing/invoices/subscription.md). You can use test clocks to simulate billing periods, which include generating and sending invoices. Read the test clocks guide to learn about specific [use cases](https://docs.stripe.com/billing/testing/test-clocks/api-advanced-usage.md#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 management** | Set up the *customer portal* (The customer portal is a secure, Stripe-hosted page that lets your customers manage their subscriptions and billing details) to let your customers manage their *subscriptions* (A Subscription represents the product details associated with the plan that your customer subscribes to. Allows you to charge the customer on a recurring basis) and billing information. To test it, create a subscription in a *sandbox* (A sandbox is an isolated test environment that allows you to test Stripe functionality in your account without affecting your live integration. Use sandboxes to safely experiment with new features and changes). 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](https://docs.stripe.com/customer-management.md) to learn how to set up the customer portal. | - `customer.subscription.deleted` - `customer.subscription.paused` - `customer.subscription.resumed` - `customer.subscription.updated` | | **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](https://docs.stripe.com/billing/testing.md#trials). For more information about how trials work, read the [subscription trials guide](https://docs.stripe.com/billing/subscriptions/trials.md). | - `customer.subscription.trial_will_end` - `customer.subscription.updated` | | **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](https://docs.stripe.com/billing/testing.md#payment-failures). | - `invoice.finalization_failed` - `invoice.payment_failed` - `invoice.payment_action_required` | ## Test clocks Test clocks allow you to simulate Billing objects, like *subscriptions* (A Subscription represents the product details associated with the plan that your customer subscribes to. Allows you to charge the customer on a recurring basis), through time in a *sandbox* (A sandbox is an isolated test environment that allows you to test Stripe functionality in your account without affecting your live integration. Use sandboxes to safely experiment with new features and changes) 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](https://docs.stripe.com/billing/testing/test-clocks.md) and common [use cases](https://docs.stripe.com/billing/testing/test-clocks.md) for them. ## Test subscription trial periods 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 simulation and set the `frozen_time` to 1 January. - Add a customer and include their payment method. In this case, use a 4242424242424242 [test card](https://docs.stripe.com/testing.md#cards). - Create a subscription and add a seven-day free trial period: #### Dashboard To add a trial period to an existing subscription using the Dashboard: Find the subscription you want to change. 1. Click **Actions**. 1. Click **Update subscription**. 1. Click **Add free trial** and enter seven in **Free trial days** field. 1. Click **Update subscription**. #### API You can start a customer’s subscription with a free trial period by providing a `trial_period_days=7` argument when creating the subscription: ```curl curl https://api.stripe.com/v1/subscriptions \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d "items[0][price]={{PRICE_ID}}" \ -d trial_end=1610403705 ``` - After creating a subscription with a seven-day free trial period, a subscription is created in a `trialling` status. An invoice of US$0.00 is generated due to the free trial. - Advance the date to 5 January to see the [customer.subscription.trial_will_end](https://docs.stripe.com/api/events/types.md#event_types-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 To test how your integration handles trial periods without waiting a full trial period to see the results, create a new *subscription* (A Subscription represents the product details associated with the plan that your customer subscribes to. Allows you to charge the customer on a recurring basis) with a `trial_end` value a few minutes in the future. If you use Checkout, set the [trial_end](https://docs.stripe.com/api/subscriptions/create.md#create_subscription-trial_end) value to at least 2 days. With this approach, you won’t see a `customer.subscription.trial_will_end` event notification, which occurs three days before a trial ends. In all other ways it behaves the same as a subscription with a longer trial period. ## Test subscription webhook notifications Subscriptions integrations rely heavily on *webhooks* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests). 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](https://docs.stripe.com/stripe-cli.md) or through the [Dashboard](https://dashboard.stripe.com/test/account/webhooks). After you set up the Stripe CLI and link to your Stripe account, you can trigger events from the [subscription lifecycle](https://docs.stripe.com/billing/subscriptions/overview.md#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. > The Accounts v2 API is in GA for Connect users, and in public preview for other Stripe users. > > Regardless of whether you use [Accounts v2](https://docs.stripe.com/connect/use-accounts-as-customers.md) objects or [Customer](https://docs.stripe.com/api/customers.md) objects to represent your customers, use the `customer.subscription` events to track subscription events. | Event | Description | | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `v2.core.account.created` | Sent when a [v2 Account](https://docs.stripe.com/api/v2/core/accounts/object.md) is successfully created. | | `customer.created` | Sent when a [Customer](https://docs.stripe.com/api/customers/object.md) is successfully created. | | `customer.subscription.created` | Sent 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](https://docs.stripe.com/api/subscriptions/create.md#create_subscription-payment_behavior). | | `customer.subscription.deleted` | Sent when a customer’s subscription ends. | | `customer.subscription.paused` | Sent when a subscription’s `status` changes to `paused`. For example, this is sent when a subscription is [configured](https://docs.stripe.com/api/subscriptions/create.md#create_subscription-trial_settings-end_behavior-missing_payment_method) to pause when a [free trial ends without a payment method](https://docs.stripe.com/billing/subscriptions/trials.md#create-free-trials-without-payment). Invoicing won’t occur until the subscription is [resumed](https://docs.stripe.com/api/subscriptions/resume.md). We don’t send this event if [payment collection is paused](https://docs.stripe.com/billing/subscriptions/pause-payment.md) because invoices continue to be created during that time period. | | `customer.subscription.resumed` | Sent when a subscription previously in a `paused` status is resumed. This doesn’t apply when [payment collection is unpaused](https://docs.stripe.com/billing/subscriptions/pause-payment.md#unpausing). | | `customer.subscription.trial_will_end` | Sent three days before the [trial period ends](https://docs.stripe.com/billing/subscriptions/trials.md). If the trial is less than three days, this event is triggered. | | `customer.subscription.updated` | Sent when a subscription starts or [changes](https://docs.stripe.com/billing/subscriptions/change.md). For example, renewing a subscription, adding a coupon, applying a discount, adding an invoice item, and changing plans all trigger this event. | | `entitlements.active_entitlement_summary.updated` | Sent when a customer’s active entitlements are updated. When you receive this event, you can provision or de-provision access to your product’s features. Read more about [integrating with entitlements](https://docs.stripe.com/billing/entitlements.md). | | `invoice.created` | Sent when an invoice is created for a new or renewing subscription. If Stripe fails to receive a successful response to `invoice.created`, then finalising all invoices with [automatic collection](https://docs.stripe.com/invoicing/integration/automatic-advancement-collection.md) is delayed for up to 72 hours. Read more about [finalising invoices](https://docs.stripe.com/invoicing/integration/workflow-transitions.md#finalized). - Respond to the notification by sending a request to the [Finalise an invoice](https://docs.stripe.com/api/invoices/finalize.md) API. | | `invoice.finalized` | Sent when an invoice is successfully finalized and ready to be paid. - You can send the invoice to the customer. View [invoice finalisation](https://docs.stripe.com/invoicing/integration/workflow-transitions.md#finalized) to learn more. - Depending on your settings, we automatically charge the default payment method or attempt collection. View [emails after finalisation](https://docs.stripe.com/invoicing/integration/workflow-transitions.md#emails) to learn more. | | `invoice.finalization_failed` | The invoice couldn’t be finalised. Learn how to [handle invoice finalisation failures](https://docs.stripe.com/tax/customer-locations.md#finalizing-invoices-with-finalization-failures) by reading the guide. Learn more about [invoice finalisation](https://docs.stripe.com/invoicing/integration/workflow-transitions.md#finalized) in the invoices overview guide. - Inspect the Invoice’s [last_finalization_error](https://docs.stripe.com/api/invoices/object.md#invoice_object-last_finalization_error) to determine the cause of the error. - If you’re using Stripe Tax, check the Invoice object’s [automatic_tax](https://docs.stripe.com/api/invoices/object.md#invoice_object-last_finalization_error) field. - If `automatic_tax[status]=requires_location_inputs`, the invoice can’t be finalised and payments can’t be collected. Notify your customer and collect the required [customer location](https://docs.stripe.com/tax/customer-locations.md). - If `automatic_tax[status]=failed`, retry the request later. | | `invoice.paid` | Sent 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_required` | Sent when the invoice requires customer authentication. Learn how to handle the subscription when the invoice [requires action](https://docs.stripe.com/billing/subscriptions/overview.md#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. - Configure your [subscription settings](https://dashboard.stripe.com/settings/billing/automatic) in the Dashboard to enable [Smart Retries](https://docs.stripe.com/billing/revenue-recovery/smart-retries.md) and other revenue recovery features. - If you’re using PaymentIntents, collect new payment information and [confirm the PaymentIntent](https://docs.stripe.com/api/payment_intents/confirm.md). - Update the [default payment method](https://docs.stripe.com/api/subscriptions/object.md#subscription_object-default_payment_method) on the subscription. | | `invoice.upcoming` | 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](https://dashboard.stripe.com/settings/billing/automatic). For existing subscriptions, changing the number of days takes effect on the next billing period. You can still add [extra invoice items](https://docs.stripe.com/billing/invoices/subscription.md#adding-upcoming-invoice-items), if needed. | | `invoice.updated` | Sent 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.created` | Sent when a [PaymentIntent](https://docs.stripe.com/api/payment_intents.md) is created. | | `payment_intent.succeeded` | Sent when a PaymentIntent has successfully completed payment. | | `subscription_schedule.aborted` | Sent when a subscription schedule is cancelled because payment delinquency terminated the related subscription. | | `subscription_schedule.canceled` | Sent when a subscription schedule is cancelled, which also cancels any active associated subscription. | | `subscription_schedule.completed` | Sent when all [phases](https://docs.stripe.com/billing/subscriptions/subscription-schedules.md#subscription-schedule-phases) of a subscription schedule complete. | | `subscription_schedule.created` | Sent when a new subscription schedule is created. | | `subscription_schedule.expiring` | Sent 7 days before a subscription schedule is set to expire. | | `subscription_schedule.released` | Sent when a subscription schedule is [released](https://docs.stripe.com/api/subscription_schedules/release.md), or stopped and disassociated from the subscription, which remains. | | `subscription_schedule.updated` | Sent when a subscription schedule is updated. | ## Test payment failures Use specific [test credit card numbers](https://docs.stripe.com/testing.md#cards) to trigger payment failures for subscriptions and *invoices* (Invoices are statements of amounts owed by a customer. They track the status of payments from draft through paid or otherwise finalized. Subscriptions automatically generate invoices, or you can manually create a one-off invoice). 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**](https://docs.stripe.com/testing.md#cards) 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](https://docs.stripe.com/invoicing/overview.md#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](https://docs.stripe.com/billing/testing/test-clocks.md) to simulate the forward movement of time in a *sandbox* (A sandbox is an isolated test environment that allows you to test Stripe functionality in your account without affecting your live integration. Use sandboxes to safely experiment with new features and changes), which causes Billing resources, like Subscriptions, to change status and trigger *webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) 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**](https://docs.stripe.com/testing.md#three-ds-cards) 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]`. 1. Find the invoice in the Dashboard and click **Send**. 1. Your customer has been allocated a unique virtual bank account number that you can retrieve through the [funding instructions API](https://docs.stripe.com/payments/customer-balance/funding-instructions.md#create-funding-instructions). 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](https://docs.stripe.com/testing.md?testing-method=payment-methods#cards) 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](https://docs.stripe.com/api/payment_methods/attach.md) endpoint with `pm_card_visa` and the intended customer for the subscription or invoice 1. 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](https://docs.stripe.com/testing.md?testing-method=payment-methods#cards) 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 the Australian Business Number (ABN), EU VAT Number, or UK Value-Added-Tax (GB VAT) number. | Number | Type | | ----------- | ----------------------------------------- | | `000000000` | Successful verification | | `111111111` | Unsuccessful verification | | `222222222` | Verification remains pending indefinitely | ## Automated testing You can set up [automated testing](https://docs.stripe.com/automated-testing.md) for your integration. To optimise the testing: - Be aware of the [data retention policy](https://support.stripe.com/questions/test-mode-subscription-data-retention) for subscription-related data in a sandbox. - Avoid re-using resources like [Coupons](https://docs.stripe.com/api/coupons.md) and [Promotion Codes](https://docs.stripe.com/api/promotion_codes.md) across tests. - Use the [stripe-mock](https://github.com/stripe/stripe-mock) HTTP server, which is based on the Stripe API and closely reflects the API’s behaviour. ## See also - [Sandboxes](https://docs.stripe.com/sandboxes.md) - [Multiple accounts](https://docs.stripe.com/get-started/account/multiple-accounts.md)