Save details for future payments with pre-authorized debit in Canada
Save payment method details for future Canadian pre-authorized debit payments.
Checkout
Direct API
You can use the Setup Intents API to collect payment method details in advance, with the final amount or payment date determined later. This is useful for:
- Saving payment methods to a wallet to streamline future purchases
- Collecting surcharges after fulfilling a service
- Starting a free trial for a subscription
Note
Pre-authorized debit in Canada is a delayed notification payment method, which means that funds aren’t immediately available after payment. A payment typically takes 5 business days to arrive in your account.
Most bank accounts in Canada hold Canadian dollars (CAD), with a small number of accounts in other currencies, including US dollars (USD). It’s possible to accept PAD payments in either CAD or USD, but choosing the correct currency for your customer is important to avoid payment failures.
Unlike many card-based payment methods, you might not be able to successfully debit a CAD account in USD or debit a USD account in CAD. Most often, attempting to do so results in a delayed payment failure that takes up to five business days.
To avoid these failures, it’s safest to set up PAD bank accounts in CAD unless you’re confident your customer’s account accepts USD debits.
Set up Stripe Server-side
First, you need a Stripe account. Register now.
Use our official libraries for access to the Stripe API from your application:
Command Line
Select a language
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
# Available as a gem
sudo gem install stripe
Gemfile
Select a language
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
# If you use bundler, you can add this line to your Gemfile
gem 'stripe'
Create or retrieve a Customer Server-side
To reuse a bank account for future payments, it must be attached to a Customer.
Create a Customer object when your customer creates an account with your business. Associating the ID of the Customer object with your own internal representation of a customer lets you retrieve and use the stored payment method details later. If your customer hasn’t created an account, you can still create a Customer object now and associate it with your internal representation of the customer’s account later.
Create a new Customer or retrieve an existing Customer to associate with these payment details. Include the following code on your server to create a new Customer.
Command Line
Select a language
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
Set up future payments
Note
This guide builds on the foundational set up future payments Checkout integration.
Enable Canadian pre-authorized debit as a payment method
When creating a new Checkout Session, you need to:
- Enable pre-authorized debit in your Dashboard. Stripe automatically displays pre-authorized debit to eligible customers using dynamic payment methods . If you currently specify payment _ method _ types , see the migration guide .
- Specify additional payment_method_options parameters to describe your transaction. Learn more below.
Payments must specify a payment schedule for customers to authorize when checking out. See PAD Mandates for details on how to choose the right mandate options for your business:
| Parameter | Value | Required |
|---|---|---|
payment_method_options[acss_debit][currency] | Currency to use for future payments with this payment method. Must match the customer’s bank account currency. Accepted values are cad or usd. | Yes |
payment_method_options[acss_debit][mandate_options][payment_schedule] | The mandate payment schedule. Accepted values are interval, sporadic, or combined. See the PAD Mandates overview to help you select the right schedule for your business. | Yes |
payment_method_options[acss_debit][mandate_options][interval_description] | Text description of the payment schedule. See the PAD Mandates overview to help you construct the right interval description for your business. | Required if payment_schedule value is interval or combined |
payment_method_options[acss_debit][mandate_options][transaction_type] | The type of transactions you’ll use the mandate for, either personal (if the transactions are for personal reasons) or business (if the transactions are for business reasons). | Yes |
payment_method_options[acss_debit][mandate_options][default_for] | An array of mandate purposes. For more information, see the PAD mandates overview to choose the right default purpose for your business. | No |
Create a Checkout session
Command Line
Select a language
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
During the Checkout session, the customer is presented with a UI modal that handles bank account details collection and instant verification with an optional fallback to verification using microdeposits. If the customer opts for microdeposit verification, Stripe automatically sends two small deposits to the provided bank account which take 1-2 business days to appear on the customer’s online bank statement. When the deposits are expected to arrive, the customer receives an email with a link to confirm these amounts and verify the bank account with Stripe. After verification is completed, the payment method is ready to be used for future payments.
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.
| Token | Scenario |
|---|---|
pm_acssDebit_success | The payment succeeds immediately after the mandate is accepted. |
pm_acssDebit_noAccount | The payment fails because no account is found. |
pm_acssDebit_accountClosed | The payment fails because the account is closed. |
pm_acssDebit_insufficientFunds | The payment fails due to insufficient funds. |
pm_acssDebit_debitNotAuthorized | The payment fails because debits aren’t authorized. |
pm_acssDebit_dispute | The payment succeeds but triggers a dispute. |
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 Number | Transit Number | Account Number | Scenario |
|---|---|---|---|
000 | 11000 | 000123456789 | Succeeds the payment immediately after micro-deposits are verified. |
000 | 11000 | 900123456789 | Succeeds the payment with a three-minute delay after micro-deposits are verified. |
000 | 11000 | 000222222227 | Fails the payment immediately after micro-deposits are verified. |
000 | 11000 | 900222222227 | Fails the payment with a three-minute delay after micro-deposits are verified. |
000 | 11000 | 000666666661 | Fails to send verification micro-deposits. |
000 | 11000 | 000777777771 | Fails the payment due to the payment amount causing the account to exceed its weekly payment volume limit. |
000 | 11000 | 000888888881 | Fails 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 Values | Scenario |
|---|---|
32 and 45 | Successfully verifies the account. |
10 and 11 | Simulates exceeding the number of allowed verification attempts. |
| Any other number combinations | Fails account verification. |
Use the payment method Server-side
After completing the Checkout Session, you can collect the PaymentMethod ID and a Mandate ID. You can use these to initiate future payments without having to prompt the customer for their bank account a second time.
Warning
Future pre-authorized debit payments must be charged according to the terms of the existing mandate. Debiting at any time that doesn’t meet the terms of the mandate could be cause for a payment dispute.
When you’re ready to charge your customer off-session, provide the payment_method, customer, and mandate IDs when creating a PaymentIntent.
If you haven’t captured the SetupIntent ID yet, look up the PaymentMethod and Mandate to charge by listing the SetupIntents associated with your customer:
Command Line
Select a language
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
Reuse a payment method with an existing authorized mandate
When you have the PaymentMethod and Mandate IDs from the applicable SetupIntent, create a PaymentIntent with the amount and currency of the payment. Set a few other parameters to make the off-session payment:
- Set the value of the PaymentIntent’s confirm property to true , which causes confirmation to occur immediately when the PaymentIntent is created.
- Set payment_method to the ID of the PaymentMethod, mandate to the ID of the Mandate, and customer to the ID of the Customer.
Command Line
Select a language
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
When reusing an existing mandate with the new PaymentIntent, a debit notification email must be sent at that time. Stripe handles this for you by default, unless you choose to send custom notifications.