# Save details for future payments with pre-authorized debit in Canada Save payment method details for future Canadian pre-authorized debit payments. # Checkout You can use the [Setup Intents API](https://docs.stripe.com/payments/setup-intents.md) 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 > 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](https://dashboard.stripe.com/register). Use our official libraries for access to the Stripe API from your application: #### Ruby ```bash # Available as a gem sudo gem install stripe ``` ```ruby # 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](https://docs.stripe.com/api/customers.md). 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. ```curl curl -X POST https://api.stripe.com/v1/customers \ -u "<>:" ``` ## Set up future payments > This guide builds on the foundational [set up future payments](https://docs.stripe.com/payments/save-and-reuse.md) Checkout integration. Use this guide to learn how to enable Canadian Pre-Authorized Debits (PADs)—it shows the differences between setting up future payments using dynamic payment methods and manually configuring payment methods and using PADs. ### Enable Canadian pre-authorized debit as a payment method When creating a new [Checkout Session](https://docs.stripe.com/api/checkout/sessions.md), you need to: 1. Add `acss_debit` to the list of `payment_method_types`. 1. Specify additional [payment_method_options](https://docs.stripe.com/api/setup_intents/create.md#create_setup_intent-payment_method_options-acss_debit) parameters to describe your transaction. Learn more below. Payments must specify a [payment schedule](https://docs.stripe.com/api/checkout/sessions/create.md#create_checkout_session-payment_method_options-acss_debit-mandate_options-payment_schedule) for customers to authorize when checking out. See [PAD Mandates](https://docs.stripe.com/payments/acss-debit.md#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](https://docs.stripe.com/payments/acss-debit.md#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](https://docs.stripe.com/payments/acss-debit.md#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](https://docs.stripe.com/payments/acss-debit.md#mandates) overview to choose the right default purpose for your business. | No | ### Create a Checkout session #### Stripe-hosted page ```curl curl https://api.stripe.com/v1/checkout/sessions \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d mode=setup \ -d "payment_method_options[acss_debit][currency]=cad" \ -d "payment_method_options[acss_debit][mandate_options][payment_schedule]=interval" \ -d "payment_method_options[acss_debit][mandate_options][interval_description]=First day of every month" \ -d "payment_method_options[acss_debit][mandate_options][transaction_type]=personal" \ -d "payment_method_types[]=acss_debit" \ --data-urlencode "success_url=https://example.com/success" ``` #### Full embedded page ```curl curl https://api.stripe.com/v1/checkout/sessions \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d mode=setup \ -d "payment_method_options[acss_debit][currency]=cad" \ -d "payment_method_options[acss_debit][mandate_options][payment_schedule]=interval" \ -d "payment_method_options[acss_debit][mandate_options][interval_description]=First day of every month" \ -d "payment_method_options[acss_debit][mandate_options][transaction_type]=personal" \ -d "payment_method_types[]=acss_debit" \ --data-urlencode "return_url=https://example.com/return" \ -d ui_mode=embedded_page ``` 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* (Confirming an intent indicates that the customer intends to use the current or provided payment method. Upon confirmation, the intent attempts to initiate the portions of the flow that have real-world side effects) 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](https://docs.stripe.com/payments/checkout/save-and-reuse.md?payment-ui=stripe-hosted#retrieve-checkout-session) the [PaymentMethod](https://docs.stripe.com/api/payment_methods.md) ID and a [Mandate](https://docs.stripe.com/api/mandates.md) ID. You can use these to initiate future payments without having to prompt the customer for their bank account a second time. > 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](https://docs.stripe.com/api/payment_intents/create.md). If you haven’t captured the SetupIntent ID yet, look up the PaymentMethod and Mandate to charge by [listing](https://docs.stripe.com/api/setup_intents/list.md) the SetupIntents associated with your customer: ```curl curl -G https://api.stripe.com/v1/setup_intents \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" ``` ### 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* (A payment is described as off-session if it occurs without the direct involvement of the customer, using previously-collected payment information): - Set the value of the PaymentIntent’s [confirm](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-confirm) property to `true`, which causes confirmation to occur immediately when the PaymentIntent is created. - Set [payment_method](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-payment_method) to the ID of the PaymentMethod, [mandate](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-mandate) to the ID of the Mandate, and [customer](https://docs.stripe.com/api/payment_intents/create.md#create_payment_intent-customer) to the ID of the Customer. ```curl curl https://api.stripe.com/v1/payment_intents \ -u "<>:" \ -d "payment_method_types[]=acss_debit" \ -d "payment_method={{PAYMENTMETHOD_ID}}" \ -d "customer={{CUSTOMER_ID}}" \ -d "mandate={{MANDATE_ID}}" \ -d confirm=true \ -d amount=100 \ -d currency=cad ``` 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](https://docs.stripe.com/payments/acss-debit.md#mandate-and-debit-notification-emails). ## Optional: Instant only verification [Server-side] By default, Canadian pre-authorized debit payments allow your customers to use instant bank account verification or micro-deposits. You can optionally require instant bank account verification only using the `payment_method_options[acss_debit][verification_method]` parameter when you create the Checkout session. #### Accounts v2 ```curl curl https://api.stripe.com/v1/checkout/sessions \ -u "<>:" \ -d mode=setup \ -d "customer_account={{CUSTOMERACCOUNT_ID}}" \ -d "payment_method_types[]=acss_debit" \ -d "payment_method_options[acss_debit][currency]=cad" \ -d "payment_method_options[acss_debit][mandate_options][payment_schedule]=interval" \ --data-urlencode "payment_method_options[acss_debit][mandate_options][interval_description]=On November 25, 2021" \ -d "payment_method_options[acss_debit][mandate_options][transaction_type]=personal" \ -d "payment_method_options[acss_debit][verification_method]=instant" \ --data-urlencode "success_url=https://example.com/success" ``` #### Customers v1 ```curl curl https://api.stripe.com/v1/checkout/sessions \ -u "<>:" \ -d mode=setup \ -d customer={{CUSTOMER_ID}} \ -d "payment_method_types[]=acss_debit" \ -d "payment_method_options[acss_debit][currency]=cad" \ -d "payment_method_options[acss_debit][mandate_options][payment_schedule]=interval" \ --data-urlencode "payment_method_options[acss_debit][mandate_options][interval_description]=On November 25, 2021" \ -d "payment_method_options[acss_debit][mandate_options][transaction_type]=personal" \ -d "payment_method_options[acss_debit][verification_method]=instant" \ --data-urlencode "success_url=https://example.com/success" ``` ## Optional: Micro-deposit only verification [Server-side] By default, Canadian pre-authorized debit payments allow your customers to use instant bank account verification or micro-deposits. You can optionally require micro-deposit verification only using the `payment_method_options[acss_debit][verification_method]` parameter when you create the Checkout session. #### Accounts v2 ```curl curl https://api.stripe.com/v1/checkout/sessions \ -u "<>:" \ -d mode=setup \ -d "customer_account={{CUSTOMERACCOUNT_ID}}" \ -d "payment_method_types[]=acss_debit" \ -d "payment_method_options[acss_debit][currency]=cad" \ -d "payment_method_options[acss_debit][mandate_options][payment_schedule]=interval" \ --data-urlencode "payment_method_options[acss_debit][mandate_options][interval_description]=On November 25, 2021" \ -d "payment_method_options[acss_debit][mandate_options][transaction_type]=personal" \ -d "payment_method_options[acss_debit][verification_method]=microdeposits" \ --data-urlencode "success_url=https://example.com/success" ``` #### Customers v1 ```curl curl https://api.stripe.com/v1/checkout/sessions \ -u "<>:" \ -d mode=setup \ -d customer={{CUSTOMER_ID}} \ -d "payment_method_types[]=acss_debit" \ -d "payment_method_options[acss_debit][currency]=cad" \ -d "payment_method_options[acss_debit][mandate_options][payment_schedule]=interval" \ --data-urlencode "payment_method_options[acss_debit][mandate_options][interval_description]=On November 25, 2021" \ -d "payment_method_options[acss_debit][mandate_options][transaction_type]=personal" \ -d "payment_method_options[acss_debit][verification_method]=microdeposits" \ --data-urlencode "success_url=https://example.com/success" ```