Check out some common scenarios to help you thoroughly test your billing integration before taking it live. You should also make use of our general testing doc, particularly its list of test credit card numbers.

Testing subscription trial periods

A common need is to test how your integration handles trial periods without waiting a full trial period to see the results. There’s a quick solution here: create a new subscription with a trial_end value only 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 the logic is the same as a subscription with a longer trial period.

Testing subscription webhook notifications

Proper use of subscriptions relies heavily on using webhooks. You can test webhooks by triggering fake event notifications via the Dashboard. However, when you do so, the received event contains only fake data that doesn’t correlate to real or test subscription information.

Using fake event notifications may suffice but 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.

In order 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 will 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 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, a 3DS dialog will appear in which you can test authenticating or failing the payment attempt. 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 via ACH credit transfers:

1. Create a testmode invoice, with the billing mode of send_invoice
2. Find the invoice in the Dashboard and click Send, or send the invoice via the API.
3. Identify the newly-created ach_credit_transfer source on the being invoiced.
4. Update the owner email on the created source to amount_XXXX@any_domain.com, where XXXX is an integer representing the amount of money transferred (e.g., to transfer $149.35, 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"

# Set your secret key: remember to change this to your live secret key in production
# See your keys here: https://dashboard.stripe.com/account/apikeys
Stripe.api_key = 'sk_test_4eC39HqLyjWDarjtT1zdp7dc'

Stripe::Source.update('src_19Q3AILlRB0eXbMt81RVDnM9', {
  owner: {email: 'amount_1000@example.com'},
})

# Set your secret key: remember to change this to your live secret key in production
# See your keys here: https://dashboard.stripe.com/account/apikeys
stripe.api_key = 'sk_test_4eC39HqLyjWDarjtT1zdp7dc'

stripe.Source.modify('src_19Q3AILlRB0eXbMt81RVDnM9',
  owner={'email': 'amount_1000@example.com'},
)

// Set your secret key: remember to change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
\Stripe\Stripe::setApiKey('sk_test_4eC39HqLyjWDarjtT1zdp7dc');

\Stripe\Source::update('src_19Q3AILlRB0eXbMt81RVDnM9', [
    'owner' => ['email' => 'amount_1000@example.com'],
]);

// Set your secret key: remember to change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
Stripe.apiKey = "sk_test_4eC39HqLyjWDarjtT1zdp7dc";

Source source = Source.retrieve("src_19Q3AILlRB0eXbMt81RVDnM9");
Map<String, Object> ownerParams = new HashMap<>();
ownerParams.put("email", "amount_1000@example.com");
Map<String, Object> params = new HashMap<>();
params.put("owner", ownerParams);
source.update(params);

// Set your secret key: remember to change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
const stripe = require('stripe')('sk_test_4eC39HqLyjWDarjtT1zdp7dc');

stripe.sources.update('src_19Q3AILlRB0eXbMt81RVDnM9', {
  owner: {
    email: 'amount_1000@example.com',
  },
});

// Set your secret key: remember to change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
stripe.Key = "sk_test_4eC39HqLyjWDarjtT1zdp7dc"

params := &stripe.SourceObjectParams{
  Owner: &stripe.SourceOwnerParams{
    Email: stripe.String("amount_1000@example.com"),
  },
}
src, _ := source.Update("src_19Q3AILlRB0eXbMt81RVDnM9", params)

// Set your secret key: remember to change this to your live secret key in production
// See your keys here: https://dashboard.stripe.com/account/apikeys
StripeConfiguration.SetApiKey("sk_test_4eC39HqLyjWDarjtT1zdp7dc");

var options = new SourceUpdateOptions {
    Owner = new SourceOwnerOptions {
        Email = "amount_1000@example.com",
    }
};
var service = new SourceService();
Source source = service.Update("src_19Q3AILlRB0eXbMt81RVDnM9", options);

Testing customer VAT number verification

Use these magic VAT numbers to trigger certain verification conditions in test mode.