Set up a subscription with pre-authorized debit in Canada

Learn how to create and charge for a subscription with Canadian pre-authorized debits.

Before you set up the related setting Debit for subscriptions, review the following availability note.

Note

Subscription mode in Checkout isn’t yet supported. To learn about early access when this feature is available, contact us to join the waiting list.

Create a product and price Dashboard

Products represent the item or service you’re selling. Prices define how much and how frequently you charge for a product. This includes how much the product costs, what currency you accept, and whether it’s a one-off or recurring charge. If you only have a few products and prices, create and manage them in the Dashboard.

This guide uses a stock photo service as an example and charges customers a 15 CAD monthly subscription. To model this:

1. Go to the Products page and click Create product .
2. Enter a Name for the product. You can optionally add a Description and upload an image of the product.
3. Select a Product tax code . Learn more about product tax codes .
4. Select Recurring . Then enter 15 for the price and select CAD as the currency.
5. Choose whether to Include tax in price . You can either use the default value from your tax settings or set the value manually. In this example, select Auto .
6. Select Monthly for the Billing period .
7. Click More pricing options . Then select Flat rate as the pricing model for this example. Learn more about flat rate and other pricing models .
8. Add an internal Price description and Lookup key to organise, query and update specific prices in the future.
9. Click Next . Then click Add product .

After you create the product and the price, record the price ID so you can use it in subsequent steps. The pricing page displays the ID and it looks similar to this: price_G0FvDp6vZvdwRZ.

Create the subscription Server-side

Note

To create a subscription with a free trial period, see Subscription trials.

Create a subscription with the price and customer with status incomplete by providing the payment_behavior parameter with the value of default_incomplete.

Command Line

Select a language

curl

Ruby

Python

PHP

Java

Node.js

Go

.NET

No results

The response includes the subscription ’s first Invoice. This contains the invoice’s payments, which includes a default PaymentIntent that Stripe generated for this invoice and the confirmation secret which you can use on the client side to securely complete the payment process instead of passing the entire PaymentIntent object. Return the latest_invoice.confirmation_secret.client_secret to the front end to complete payment.

Collect payment method details and mandate acknowledgment Client-side

To use Canadian pre-authorised debits, you must obtain authorisation from your customer for one-off and recurring debits using a pre-authorised debit agreement (see PAD Mandates). The Mandate object records this agreement and authorisation.

Stripe automatically configures subscription and invoice mandates for you. The customer only needs to acknowledge the mandate terms once, subsequent subscription charges will succeed without further intervention.

When a customer clicks to pay with Canadian pre-authorized debit, we recommend you use Stripe.js to submit the payment to Stripe. Stripe.js is our foundational JavaScript library for building payment flows. It will automatically handle integration complexities, and enables you to easily extend your integration to other payment methods in the future.

Include the Stripe.js script on your checkout page by adding it to the head of your HTML file.

checkout.html

Create an instance of Stripe.js with the following JavaScript on your checkout page.

client.js

// Set your publishable key. Remember to change this to your live publishable key in production!
// See your keys here: https://dashboard.stripe.com/apikeys
const stripe = Stripe('pk_test_GvF3BSyx8RSXMK5yAFhqEd3H');

Rather than sending the entire PaymentIntent object to the client, use its client secret from the previous step. This is different from your API keys that authenticate Stripe API requests.

The client secret should still be handled carefully because it can complete the charge. Don’t log it, embed it in URLs, or expose it to anyone but the customer.

Use stripe.confirmAcssDebitPayment to collect bank account details and verification, confirm the mandate, and complete the payment when the user submits the form. Including the customer’s email address and the account holder’s name in the billing_details property of the payment_method parameter is required to create a PAD payment method.

const form = document.getElementById('payment-form');
const accountholderName = document.getElementById('accountholder-name');
const email = document.getElementById('email');
const submitButton = document.getElementById('submit-button');
const clientSecret = submitButton.dataset.secret;

form.addEventListener('submit', async (event) => {
 event.preventDefault();

 const {paymentIntent, error} = await stripe.confirmAcssDebitPayment(
 clientSecret,
 {
 payment_method: {
 billing_details: {
 name: accountholderName.value,
 email: email.value,
 },
 },
 }
 );

 if (error) {
 // Inform the customer that there was an error.
 console.log(error.message);
 } else {
 // Handle next step based on PaymentIntent's status.
 console.log("PaymentIntent ID: " + paymentIntent.id);
 console.log("PaymentIntent status: " + paymentIntent.status);
 }
});

Stripe.js then loads an on-page modal UI that handles bank account details collection and verification, presents a hosted mandate agreement and collects authorization.

Note

stripe.confirmAcssDebitPayment might take several seconds to complete. During that time, disable your form from being resubmitted and show a waiting indicator such as a spinner. If you receive an error, show it to the customer, re-enable the form and hide the waiting indicator.

If the customer completes instant verification, the subscription automatically becomes active. Otherwise, consult the following section to handle micro-deposit verification while the subscription remains incomplete.

Verify bank account with micro-deposits Client-side

Note

Customers have 10 days to successfully verify micro-deposits for a subscription, instead of the 23 hours normally given in the subscription lifecycle. However, this expiry can’t be later than the billing period date.

Not all customers can verify the bank account instantly. This step only applies if your customer has elected to opt out of the instant verification flow in the previous step.

In this case, Stripe automatically sends two micro-deposits to the customer’s bank account. These deposits take 1-2 business days to appear on the customer’s online statement and have statement descriptors that include the related setting.

The result of the stripe.confirmAcssDebitPayment method call in the previous step is a PaymentIntent in the requires_action state. The PaymentIntent contains a next_action field that contains some useful information for completing the verification.

Stripe notifies your customer at the billing email when the deposits are expected to arrive. The email includes a link to a Stripe-hosted verification page where they can confirm the amounts of the deposits and complete verification.

There is a limit of three failed verification attempts. If this limit is exceeded, the bank account can no longer be verified. In addition, there is a timeout for micro-deposit verifications of 10 days. If micro-deposits aren’t verified in that time, the PaymentIntent reverts to requiring new payment method details. Clear messaging about what these micro-deposits are and how you use them can help your customers avoid verification issues.

Optional: Custom email and verification page

If you choose to send custom email notifications, you have to email your customer instead. To do this, you can use the verify_with_microdeposits[hosted_verification_url] URL in the next_action object to direct your customer to complete the verification process.

If you’re sending custom emails and don’t want to use the Stripe hosted verification page, you can create a form on your site for your customers to relay these amounts to you and verify the bank account using Stripe.js.

stripe.verifyMicrodepositsForPayment(clientSecret, {
 amounts: [32, 45],
});

Set the default payment method Server

You now have an active subscription belonging to a customer with a payment method, but this payment method isn’t automatically used for future payments. To automatically bill this payment method in the future, use a webhook consumer to listen to the invoice.payment_succeeded event for new subscriptions and set the default payment method.

server.rb

Select a language

Ruby

Python

PHP

Java

Node.js

Go

.NET

No results

# Don't put any keys in code. See https://docs.stripe.com/keys-best-practices.
# Find your keys at https://dashboard.stripe.com/apikeys.
client = Stripe::StripeClient.new('sk_test_Ou1w6LVt3zmVipDVJsvMeQsc')

if event.type == 'invoice.payment_succeeded'
 invoice = event.data.object
 if invoice['billing_reason'] == 'subscription_create'
 subscription_id = invoice['parent']['subscription_details']['subscription']

 # This example assumes you're using the default PaymentIntent that Stripe generated for the invoice.
 invoice_payments = client.v1.invoice_payments.list({invoice: invoice['id']})
 payment_intent_id = invoice_payments.data[0].payment.payment_intent

 # Retrieve the payment intent used to pay the subscription
 payment_intent = client.v1.payment_intents.retrieve(payment_intent_id)

 # Set the default payment method
 client.v1.subscriptions.update(
 subscription_id,
 default_payment_method: payment_intent.payment_method
 )
 end
end

Manage subscription status Client-side

A subscription can become active while its first payment is still processing, so don’t use the subscription status alone to determine whether the payment succeeded. Before fulfilling goods or services, wait for the invoice.paid event or confirm that the underlying PaymentIntent has a succeeded status, and verify that the related subscription is active.

When payments fail, the status changes to the Subscription status configured in your automatic collection settings. Notify the customer after a failure and charge them with a different payment method.

Note

Canadian pre-authorised debit payments are never automatically retried, even if you have a retry schedule configured for other payment methods.

Test your integration

Test payment method tokens

Use test payment method tokens to test your integration without needing to manually enter bank account details. These tokens bypass the bank account collection and verification steps.

Test account numbers

Stripe provides several test account numbers you can use to make sure your integration for manually-entered bank accounts is ready for production. All test accounts that automatically succeed or fail the payment must be verified using the test micro-deposit amounts below before they can be completed.

To mimic successful or failed bank account verifications in a sandbox, use these meaningful amounts for micro-deposits:

Optional Setting the billing period

Optional Subscription trials

Optional Saving payment method details for future use