Skip to content
Create account
 or
Sign in
The Stripe Docs logo
/
Create account
Sign in
Overview
Billing
OverviewAbout the Billing APIs
Subscriptions
Tax
Overview
Reporting
OverviewReports for multiple accounts
Data
OverviewSchema

Set up a subscription with pre-authorized debit in Canada

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

Note

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

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-time 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 organize, 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
curl
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/subscriptions \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d "customer"="{{CUSTOMER_ID}}" \
  -d "items[0][price]"="price_F52b2UdntfQsfR" \
  -d "payment_behavior"="default_incomplete" \
  -d "payment_settings[payment_method_types][]"="acss_debit" \
  -d "expand[0]"="latest_invoice.payment_intent"

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-authorized debits, you must obtain authorization from your customer for one-time and recurring debits using a pre-authorized debit agreement (see PAD Mandates). The Mandate object records this agreement and authorization.

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
<head>
  <title>Checkout</title>
  <script src="https://js.stripe.com/basil/stripe.js"></script>
</head>

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_TYooMQauvdEDq54NiTphI7jx'
);

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. Do not 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 may take several seconds to complete. During that time, disable your form from being resubmitted and show a waiting indicator like 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 expiration 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 ACCTVERIFY.

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 are not 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 are 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
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
# Set your secret key. Remember to switch to your live secret key in production.
# See your keys here: https://dashboard.stripe.com/apikeys
Stripe.api_key = 
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'


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 = Stripe::InvoicePayment.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 = Stripe::PaymentIntent.retrieve(payment_intent_id)

    # Set the default payment method
    Stripe::Subscription.update(
      subscription_id,
      default_payment_method: payment_intent.payment_method
    )
  end
end

Manage subscription status
Client-side

When the initial payment succeeds, the status of the subscription is active and requires no further action. 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-authorized debit payments are never automatically retried, even if you have a retry schedule configured for other payment methods.

Test your integration

Receive micro-deposit verification email

To receive the micro-deposit verification email in a sandbox after collecting the bank account details and accepting a mandate, provide an email in the payment_method[billing_details][email] field in the form of {any_prefix}+test_email@{any_domain} when confirming the payment method details.

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.

Institution NumberTransit NumberAccount NumberScenario
00011000000123456789Succeeds the payment immediately after micro-deposits are verified.
00011000900123456789Succeeds the payment with a three-minute delay after micro-deposits are verified.
00011000000222222227Fails the payment immediately after micro-deposits are verified.
00011000900222222227Fails the payment with a three-minute delay after micro-deposits are verified.
00011000000666666661Fails to send verification micro-deposits.
00011000000777777771Fails the payment due to the payment amount causing the account to exceed its weekly payment volume limit.
00011000000888888881Fails the payment due to the payment amount exceeding the account’s transaction limit.

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

Micro-deposit ValuesScenario
32 and 45Successfully verifies the account.
10 and 11Simulates exceeding the number of allowed verification attempts.
Any other number combinationsFails account verification.

OptionalSetting the billing period

When you create a subscription, it automatically sets the billing cycle by default. For example, if a customer subscribes to a monthly plan on September 7, they’re billed on the 7th of every month after that. Some businesses prefer to set the billing cycle manually so that they can charge their customers at the same time each cycle. The billing cycle anchor argument allows you to do this.

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/subscriptions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d customer=
{{CUSTOMER_ID}}
 \
  -d "items[0][price]"=
{{PRICE_ID}}
 \
  -d billing_cycle_anchor=1611008505

Setting the billing cycle manually automatically charges the customer a prorated amount for the time between the subscription being created and the billing cycle anchor. If you don’t want to charge customers for this time, you can set the proration_behavior argument to none. You can also combine the billing cycle anchor with trial periods to give users free access to your product and then charge them a prorated amount.

OptionalSubscription trials

Free trials allow customers access to your product for a period of time without charging them. To set a trial period, pass a timestamp in trial_end .

Note

Using free trials is different from setting proration_behavior to none because you can customize how long the free period lasts.

When you start a subscription with a trial period using the payment_behavior value default_incomplete, Stripe returns a pending_setup_intent value in the Subscription object. Read the docs to learn more about the SetupIntent object.

Command Line
curl
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/subscriptions \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d "customer"="cus_4fdAW5ftNQow1a" \
  -d "items[0][price]"="price_CBb6IXqvTLXp3f" \
  -d "payment_behavior"="default_incomplete" \
  -d "payment_settings[payment_method_types][]"="acss_debit" \
  -d "trial_end"=1610403705 \
  -d "expand[0]"="pending_setup_intent"

Return the client_secret from the subscription’s pending_setup_intent to the frontend to complete the setup. This step is required to successfully initiate a charge for the first billing cycle.

Follow the instructions in Collect payment method details and mandate acknowledgment and Verify bank account with micro-deposits, but use stripe.confirmAcssDebitSetup instead of stripe.confirmAcssDebitPayment. If your customer chooses micro-deposit verification, use stripe.verifyMicrodepositsForSetup instead of stripe.verifyMicrodepositsForPayment.

The SetupIntent immediately transitions to succeeded status upon verification, and Stripe automatically sets the subscription’s default_payment_method to the newly created PaymentMethod.

You can also combine a billing cycle anchor with a free trial. For example, on September 15 you want to give your customer a free trial for seven days and then start the normal billing period on October 1. You can set the free trial to end on September 22 and the billing cycle anchor to October 1. This gives the customer a free trial for seven days and then charges a prorated amount for the time between the trial ending and October 1. On October 1, you charge them the normal subscription amount for their first full billing period.

OptionalSaving payment method details for future use

You might also want to save your customer’s Canadian pre-authorized debit payment method for automatic use with invoices, subscriptions, or subscription schedules that you create later.

You can do this using a SetupIntent object, which represents your intent to save a customer’s payment method for future payments. The SetupIntent tracks the steps of this set-up process.

Follow the instructions for Saving details for future payments with pre-authorized debit in Canada, but provide a different set of mandate_options to collect authorization for subscriptions and invoices.

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/setup_intents \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "payment_method_types[]"=acss_debit \
  -d customer={{CUSTOMER_ID}} \
  -d "payment_method_options[acss_debit][currency]"=cad \
  -d "payment_method_options[acss_debit][mandate_options][default_for][]"=invoice \
  -d "payment_method_options[acss_debit][mandate_options][default_for][]"=subscription

After the SetupIntent reaches the succeeded state, update your customer’s default_payment_method.

server.rb
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
# Set your secret key. Remember to switch to your live secret key in production.
# See your keys here: https://dashboard.stripe.com/apikeys
Stripe.api_key = 
'sk_test_BQokikJOvBiI2HlWgH4olfQ2'


if event.type == 'setup_intent.succeeded'
  setup_intent = event.data.object
  customer_id = setup_intent['customer']
  payment_method_id = setup_intent['payment_method']

  # Set the default payment method
  Stripe::Customer.update(
    customer_id,
    {
      invoice_settings: {
        default_payment_method: payment_method_id
      }
    }
  )
end
Was this page helpful?
YesNo