Save details for future payments with ACH Direct Debit

Server-side

This integration requires endpoints on your server that talk to the Stripe API. Use our official libraries for access to the Stripe API from your server:

Client-side

The React Native SDK is open source and fully documented. Internally, it uses the native iOS and Android SDKs. To install Stripe’s React Native SDK, run one of the following commands in your project’s directory (depending on which package manager you use):

Next, install some other necessary dependencies:

• For iOS, go to the ios directory and run pod install to ensure that you also install the required native dependencies.
• For Android, there are no more dependencies to install.

Stripe initialisation

To initialise Stripe in your React Native app, either wrap your payment screen with the StripeProvider component, or use the initStripe initialisation method. Only the API publishable key in publishableKey is required. The following example shows how to initialise Stripe using the StripeProvider component.

Create a Customer 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 optimisation.

A SetupIntent is an object that represents your intent to set up a customer’s payment method for future payments. The SetupIntent tracks the steps of this set-up process.

Create a SetupIntent on your server with payment_method_types set to us_bank_account and specify the Customer’s id.

Server-side

Create a SetupIntent on your server with payment_method_types set to us_bank_account and specify the Customer’s id.

By default, collecting bank account payment information uses Financial Connections to instantly verify your customer’s account, with a fallback option of manual account number entry and microdeposit verification. See the Financial Connections docs to learn how to configure Financial Connections and access additional account data to optimise your ACH integration. For example, you can use Financial Connections to check an account’s balance before initiating the ACH payment.

Client-side

A SetupIntent includes a client secret. You can use the client secret in your React Native app to securely complete the payment process instead of passing back the entire SetupIntent object. In your app, request a SetupIntent from your server and store its client secret.

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

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

Use collectBankAccountForSetup to collect bank account details, create a PaymentMethod, and attach that PaymentMethod to the SetupIntent. You must include the account holder’s name in the billingDetails parameter to create an ACH Direct Debit PaymentMethod.

This loads a modal UI that handles bank account details collection and verification. When it completes, the PaymentMethod is automatically attached to the SetupIntent.

When a customer exits your app (for example to authenticate in Safari or their banking app), provide a way for them to automatically return to your app. Many payment method types require a return URL. If you don’t provide one, we can’t present payment methods that require a return URL to your users, even if you’ve enabled them.

To provide a return URL:

1. Register a custom URL. Universal links aren’t supported.
2. Configure your custom URL.
3. Set up your root component to forward the URL to the Stripe SDK as shown below.

For more information on native URL schemes, refer to the Android and iOS docs.

Before you can complete the SetupIntent and save the payment method details for the customer, you must obtain authorization for payment by displaying mandate terms for the customer to accept.

To comply with Nacha rules, you must obtain authorisation from your customer before you can initiate payment by displaying mandate terms for them to accept. For more information on mandates, see Mandates.

When the customer accepts the mandate terms, you must confirm the SetupIntent. Use confirmSetup to confirm the intent.

If successful, Stripe returns a SetupIntent object, with one of the following possible statuses:

After successfully confirming the SetupIntent, an email confirmation of the mandate and collected bank account details must be sent to your customer. Stripe handles these by default, but you can choose to send custom notifications if you prefer.

Not all customers can verify their bank account instantly. In these cases, Stripe sends a microdeposit to the bank account. This deposit might take up to 1-2 business days to appear on the customer’s online statement. This deposit takes one of two shapes:

• Descriptor code. Stripe sends a single, 0.01 USD microdeposit to the customer’s bank account with a unique, 6-digit descriptorCode that starts with SM. Your customer uses this string to verify their bank account.
• Amount. Stripe sends two, non-unique microdeposits to the customer’s bank account, with a statement descriptor that reads ACCTVERIFY. Your customer uses the deposit amounts to verify their bank account.

If the result of the confirmSetup method call in the previous step is a SetupIntent with a requiresAction status, the SetupIntent contains a next_action field that contains some useful information for completing the verification.

If you supplied a billing email, Stripe uses this email to notify your customer when we expect the deposits 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.

When you know the payment is in the requiresAction state and the nextAction is of type verifyWithMicrodeposits, you can complete verification of a bank account in two ways:

1. Verify the deposits directly in your app by calling verifyMicrodepositsForSetup after collecting either the descriptor code or amounts.

1. Use the Stripe-hosted verification page that we automatically provide for you. To do this, use the nextAction[redirectUrl] URL in the nextAction object (see above) to direct your customer to complete the verification process.

When the bank account is successfully verified, Stripe returns the SetupIntent object with a status of Succeeded, and sends a setup_intent.succeeded webhook event.

Verification can fail for several reasons. The failure might happen synchronously as a direct error response, or asynchronously through a setup_intent.setup_failed webhook event (shown in the following examples).

Learn how to test scenarios with instant verifications using Financial Connections.

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.

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 are routed correctly. If you don’t include the +test_email suffix, we won’t send the email.

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.

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.

Test settlement behaviour

Test transactions settle instantly and are added to your available test balance. This behaviour differs from live mode, where transactions can take multiple days to settle in your available balance.

When the SetupIntent succeeds, it creates a new PaymentMethod attached to a Customer. You can use these to initiate future payments without having to prompt the customer for their bank account a second time.