# Save details for future payments with ACH Direct Debit Learn how to save payment method details for future ACH Direct Debit payments. # Checkout You can use Checkout in [setup mode](https://docs.stripe.com/api/checkout/sessions/object.md#checkout_session_object-mode) 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* (A Subscription represents the product details associated with the plan that your customer subscribes to. Allows you to charge the customer on a recurring basis) > ACH Direct Debit is a [delayed notification](https://docs.stripe.com/payments/payment-methods.md#payment-notification) payment method, which means that funds aren’t immediately available after payment. A payment typically takes 4 business days to arrive in your account. ## Before you begin This guide shows you how to extend the foundational [set up future payments](https://docs.stripe.com/payments/save-and-reuse.md?platform=web&ui=stripe-hosted) Checkout integration to add support for ACH Direct Debit payments. ## Create or retrieve a customer [Recommended] [Server-side] > #### Use the Accounts v2 API to represent customers > > The Accounts v2 API is generally available for Connect users, and in public preview for other Stripe users. If you’re part of the Accounts v2 preview, you need to specify a [specify a preview version](https://docs.stripe.com/api-v2-overview.md#sdk-and-api-versioning) in your code. > > To request access to the Accounts v2 preview, > > For most use cases, we recommend [modeling your customers as customer-configured Account objects](https://docs.stripe.com/accounts-v2/use-accounts-as-customers.md) instead of using [Customer](https://docs.stripe.com/api/customers.md) objects. #### Accounts v2 Create a customer-configured [Account](https://docs.stripe.com/api/v2/core/accounts/object.md#v2_account_object-configuration-customer) object when your user creates an account with your business, or retrieve an existing `Account` associated with this user. Associating the ID of the `Account` object with your own internal representation of a customer enables you to retrieve and use the stored payment method details later. Include an email address on the `Account` to enable Financial Connections’ [return user optimization](https://docs.stripe.com/financial-connections/fundamentals.md#return-user-optimization). ```curl curl -X POST https://api.stripe.com/v2/core/accounts \ -H "Authorization: Bearer <>" \ -H "Stripe-Version: 2026-05-27.preview" \ --json '{ "contact_email": "{{CUSTOMER_EMAIL}}" }' ``` #### Customers v1 Create a *Customer* (Customer objects represent customers of your business. They let you reuse payment methods and give you the ability to track multiple payments) object when your user creates an account with your business, or retrieve an existing `Customer` associated with this user. Associating the ID of the `Customer` object with your own internal representation of a customer enables you to retrieve and use the stored payment method details later. Include an email address on the `Customer` to enable Financial Connections’ [return user optimization](https://docs.stripe.com/financial-connections/fundamentals.md#return-user-optimization). ```curl curl https://api.stripe.com/v1/customers \ -u "<>:" \ -d email={{CUSTOMER_EMAIL}} ``` ## Enable ACH Direct Debit as a payment method When creating a new [Checkout Session](https://docs.stripe.com/api/checkout/sessions.md), you need to: 1. Add `us_bank_account` to the list of `payment_method_types`. 1. Set the `permissions` parameter to include `payment_method`. #### Stripe-hosted page #### Accounts v2 ```curl curl https://api.stripe.com/v1/checkout/sessions \ -u "<>:" \ -d "customer_account={{CUSTOMERACCOUNT_ID}}" \ -d mode=setup \ -d "payment_method_options[us_bank_account][financial_connections][permissions][]=payment_method" \ -d "payment_method_types[]=card" \ -d "payment_method_types[]=us_bank_account" \ --data-urlencode "success_url=https://example.com/success" ``` #### Customers v1 ```curl curl https://api.stripe.com/v1/checkout/sessions \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d mode=setup \ -d "payment_method_options[us_bank_account][financial_connections][permissions][]=payment_method" \ -d "payment_method_types[]=card" \ -d "payment_method_types[]=us_bank_account" \ --data-urlencode "success_url=https://example.com/success" ``` #### Full embedded page #### Accounts v2 ```curl curl https://api.stripe.com/v1/checkout/sessions \ -u "<>:" \ -d "customer_account={{CUSTOMERACCOUNT_ID}}" \ -d mode=setup \ -d "payment_method_options[us_bank_account][financial_connections][permissions][]=payment_method" \ -d "payment_method_types[]=card" \ -d "payment_method_types[]=us_bank_account" \ --data-urlencode "return_url=https://example.com/return" \ -d ui_mode=embedded_page ``` #### Customers v1 ```curl curl https://api.stripe.com/v1/checkout/sessions \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d mode=setup \ -d "payment_method_options[us_bank_account][financial_connections][permissions][]=payment_method" \ -d "payment_method_types[]=card" \ -d "payment_method_types[]=us_bank_account" \ --data-urlencode "return_url=https://example.com/return" \ -d ui_mode=embedded_page ``` For more information on Financial Connections fees, see [pricing details](https://stripe.com/financial-connections#pricing). By default, collecting bank account payment information uses [Financial Connections](https://docs.stripe.com/financial-connections.md) to instantly verify your customer’s account, with a fallback option of manual account number entry and microdeposit verification. See the [Financial Connections docs](https://docs.stripe.com/financial-connections/ach-direct-debit-payments.md) to learn how to configure Financial Connections and access additional account data to optimize your ACH integration. For example, you can use Financial Connections to check an account’s balance before initiating the ACH payment. > To expand access to additional data after a customer authenticates their account, they must re-link their account with expanded permissions. During the Checkout session, the customer sees a dialog that gives them the option to use instant verification or provide bank account details for microdeposit verification. If the customer opts for microdeposit verification, Stripe automatically sends two small deposits to the provided bank account. These deposits can take 1-2 business days to appear on the customer’s online bank statement. When the deposits arrive, the customer receives an email with a link to confirm these amounts and verify the bank account with Stripe. After verification completes, the payment begins processing. ## Test your integration Learn how to test scenarios with instant verifications using [Financial Connections](https://docs.stripe.com/financial-connections/testing.md#web-how-to-use-test-accounts). ### Send transaction emails in a sandbox After you collect the bank account details and accept a mandate, send the mandate confirmation and microdeposit verification emails in a *sandbox* (A sandbox is an isolated test environment that allows you to test Stripe functionality in your account without affecting your live integration. Use sandboxes to safely experiment with new features and changes). If your domain is **{domain}** and your username is **{username}**, use the following email format to send test transaction emails: **{username}+test\_email@{domain}**. For example, if your domain is **example.com** and your username is **info**, use the format **info+test\_email@example.com** for testing ACH Direct Debit payments. This format ensures that emails route correctly. If you don’t include the **+test\_email** suffix, we won’t send the email. > You must [set up your Stripe account](https://docs.stripe.com/get-started/account/set-up.md) before you can trigger these emails while testing. ### Test account numbers Stripe provides several test account numbers and corresponding tokens you can use to make sure your integration for manually-entered bank accounts is ready for production. | Account number | Token | Routing number | Behavior | | -------------- | -------------------------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | `000123456789` | `pm_usBankAccount_success` | `110000000` | The payment succeeds. | | `000111111113` | `pm_usBankAccount_accountClosed` | `110000000` | The payment fails because the account is closed. | | `000000004954` | `pm_usBankAccount_riskLevelHighest` | `110000000` | The payment is blocked by Radar due to a [high risk of fraud](https://docs.stripe.com/radar/risk-evaluation.md#high-risk). | | `000111111116` | `pm_usBankAccount_noAccount` | `110000000` | The payment fails because no account is found. | | `000222222227` | `pm_usBankAccount_insufficientFunds` | `110000000` | The payment fails due to insufficient funds. | | `000333333335` | `pm_usBankAccount_debitNotAuthorized` | `110000000` | The payment fails because debits aren’t authorized. | | `000444444440` | `pm_usBankAccount_invalidCurrency` | `110000000` | The payment fails due to invalid currency. | | `000666666661` | `pm_usBankAccount_failMicrodeposits` | `110000000` | The payment fails to send microdeposits. | | `000555555559` | `pm_usBankAccount_dispute` | `110000000` | The payment triggers a dispute. | | `000000000009` | `pm_usBankAccount_processing` | `110000000` | The payment stays in processing indefinitely. Useful for testing [PaymentIntent cancellation](https://docs.stripe.com/api/payment_intents/cancel.md). | | `000777777771` | `pm_usBankAccount_weeklyLimitExceeded` | `110000000` | The payment fails due to payment amount causing the account to exceed its weekly payment volume limit. | | `000888888885` | | `110000000` | The payment fails because of a deactivated [tokenized account number](https://docs.stripe.com/financial-connections/tokenized-account-numbers.md). | Before test transactions can complete, you need to verify all test accounts that automatically succeed or fail the payment. To do so, use the test microdeposit amounts or descriptor codes below. ### Test microdeposit amounts and descriptor codes To mimic different scenarios, use these microdeposit amounts *or* 0.01 descriptor code values. | Microdeposit values | 0.01 descriptor code values | Scenario | | ------------------- | --------------------------- | ---------------------------------------------------------------- | | `32` and `45` | SM11AA | Simulates verifying the account. | | `10` and `11` | SM33CC | Simulates exceeding the number of allowed verification attempts. | | `40` and `41` | SM44DD | Simulates a microdeposit timeout. | ### Test settlement behavior Test transactions settle instantly and are added to your available test balance. This behavior differs from livemode, where transactions can take [multiple days](https://docs.stripe.com/payments/ach-direct-debit/set-up-payment.md#timing) to settle in your available balance. ## Use the payment method 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. You can use these PaymentMethod IDs to initiate future payments without having to prompt the customer for their bank account a second time. When [creating a PaymentIntent](https://docs.stripe.com/api/payment_intents/create.md), provide the `payment_method` and customer IDs to charge your customer using their saved bank account information. ## Optional: Instant only verification By default, ACH Direct Debit payments allow your customers to use instant bank account verification or microdeposits. You can optionally require instant bank account verification only, using the `payment_method_options[us_bank_account][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[]=card" \ -d "payment_method_types[]=us_bank_account" \ -d "payment_method_options[us_bank_account][verification_method]=instant" \ -d "payment_method_options[us_bank_account][financial_connections][permissions][]=payment_method" \ -d "payment_method_options[us_bank_account][financial_connections][permissions][]=balances" \ --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[]=card" \ -d "payment_method_types[]=us_bank_account" \ -d "payment_method_options[us_bank_account][verification_method]=instant" \ -d "payment_method_options[us_bank_account][financial_connections][permissions][]=payment_method" \ -d "payment_method_options[us_bank_account][financial_connections][permissions][]=balances" \ --data-urlencode "success_url=https://example.com/success" ``` ## Optional: Access data on a Financial Connections bank account You can only access Financial Connections data if you request additional [data permissions](https://docs.stripe.com/financial-connections/fundamentals.md#data-permissions) when you create your SetupIntent. After your customer successfully completes the [Stripe Financial Connections authentication flow](https://docs.stripe.com/financial-connections/fundamentals.md#authentication-flow), the `us_bank_account` PaymentMethod returned includes a [financial_connections_account](https://docs.stripe.com/api/payment_methods/object.md#payment_method_object-us_bank_account-financial_connections_account) ID that points to a [Financial Connections Account](https://docs.stripe.com/api/financial_connections/accounts.md). Use this ID to access account data. > Bank accounts that your customers link through manual entry and microdeposits don’t have a `financial_connections_account` ID on the Payment Method. To determine the Financial Connections account ID, retrieve the SetupIntent and expand the `payment_method` attribute: ```curl curl -G https://api.stripe.com/v1/setup_intents/{{SETUPINTENT_ID}} \ -u "<>:" \ -d "expand[]=payment_method" ``` ```json { "id": "{{SETUP_INTENT_ID}}", "object": "setup_intent", // ... "payment_method": { "id": "{{PAYMENT_METHOD_ID}}", // ... "type": "us_bank_account" "us_bank_account": { "account_holder_type": "individual", "account_type": "checking", "bank_name": "TEST BANK","financial_connections_account": "{{FINANCIAL_CONNECTIONS_ACCOUNT_ID}}", "fingerprint": "q9qchffggRjlX2tb", "last4": "6789", "routing_number": "110000000" } } // ... } ``` If you have access to balances data, we recommend [checking balances](https://docs.stripe.com/financial-connections/balances.md#initiate-balance-refresh) before initiating payments with the collected Payment Method. Learn more about using additional account data to optimize your ACH integration with [Financial Connections](https://docs.stripe.com/financial-connections/ach-direct-debit-payments.md#optimize). ## Optional: Updating the default payment method After the `SetupIntent` reaches the `succeeded` state, you can update your customer’s `default_payment_method`. #### Ruby ```ruby # 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('<>') 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 client.v1.customers.update( customer_id, { invoice_settings: { default_payment_method: payment_method_id } } ) end ```