ACH via Stripe: Drop In Guide

Integrate ACH via Stripe on your website or mobile application with just a few lines of code.

Before you begin

This guide assumes that you know how to

• Show Drop-in Checkout

Accept payments with ACH via Stripe

Prepare the client session

ACH via Stripe requires the following data to process a payment successfully. Pass the following data in the client session, or in the payment request (for manual payment creation).

Parameter Name	Required	Description
currencyCode	✓	3-letter currency code in ISO 4217 format. For ACH via Stripe, only USD is supported.
order ↳ lineItems	✓	Details of the line items of the order
metadata	✓	In order to have ACH via Stripe successful, you need to pass your device info: IP address and user agent in the metadata.metadata.deviceInfo.ipAddress and metadata.deviceInfo.userAgent
paymentMethod	✓

JSX

"paymentMethod": {
    "vaultOnAgreement": true,
    "paymentType": "FIRST_PAYMENT"
  }

That should be passed if one wishes to vault ACH via Stripe.

Prepare the SDK for payments

Web

Show Universal Checkout

Pass device info when creating the client session ACH via Stripe requires that a mandate is accepted before the payment is completed.

Mandates that are accepted online require IP address and user-agent of the device that the payment is made from.

Specify this information when creating the client session, otherwise payments will remain in Pending state.

JSON

{
  ...
  "customer": {
    "emailAddress": "...",
    ...
  },
  "metadata": {
    "deviceInfo": {
      "ipAddress": "127.0.0.1", // IP address of the device accepting the mandate
      "userAgent": "Mozilla/5.0" // user-agent of the device accepting the mandate
    }
  },
  ...
}

Universal Checkout

ACH via Stripe is automatically presented to the customer when calling Primer.showUniversalCheckout with the Stripe publishable key set up.

Typescript

const options = {
    /* Other options... */
    stripe: {
        publishableKey: 'pk_...',
    }
}

Additionally, ACH via Stripe requires to show a Mandate to the user. You can either pass the full mandate text yourself via SDK options, or pass a merchant name and rely on the mandate text Primer provides you with.

JSX

const options = {
    /* Other options... */
    stripe: {
        publishableKey: 'pk_...',
        mandateData: {
          merchantName?: "Your Merchant Name", 
          fullMandateText?: "Your mandate text" // you can either pass merchantName or fullMandateText, not two at the same time.
          // In the case of passing a fullMandateText, you need to pass it localized already. 
        }
    }
}

Customization

Check the customization guide to learn how to customize payment method buttons.

Typescript

const options = {
  /* Other options ... */
  style: {
    paymentMethodButton: {
      background: string,
      borderRadius: number | string,
      boxShadow: string,
      borderColor: string,
      height: number,
      primaryText: TextStyle,
      logoColor: logoColor,
      marginTop: string,
    },
  },
}

iOS

Pre-requisites

Pass device info when creating the client session

ACH via Stripe requires that a mandate is accepted before the payment is completed.

Mandates that are accepted online require IP address and user-agent of the device that the payment is made from.

Specify this information when creating the client session, otherwise payments will remain in Pending state.

JSON

{
  ...
  "customer": {
    "emailAddress": "...",
    ...
  },
  "metadata": {
    "deviceInfo": {
      "ipAddress": "127.0.0.1", // IP address of the device accepting the mandate
      "userAgent": "Mozilla/5.0" // user-agent of the device accepting the mandate
    }
  },
  ...
}

Define the Primer Stripe dependency

In order to be able to use ACH via Stripe you will have to install PrimerStripeSDK which is available via CocoaPods.

RUBY

use_frameworks!
target 'PrimerSDK_Example' do
  pod 'PrimerSDK'
  # Add the line below 👇
  pod 'PrimerStripeSDK'
end

Define the Stripe publishable key and mandate information

It is important that you specify your Stripe publishable key along with mandate information when creating PrimerSettings, otherwise you’ll encounter errors at app runtime.

ACH via Stripe requires that a mandate is displayed before the payment is completed. This mandate will display automatically once a bank account is chosen.

The drop-in implementation provides two ways for customizing the mandate.

• you specify only your business’s name and the SDK will use a predefined template:

By clicking Accept, you authorize [Business Name] to debit the selected bank account for any amount owed for charges arising from your use of [Business Name]‘s services and/or purchase of products from [Business Name], pursuant to [Business Name]‘s website and terms, until this authorization is revoked. You may amend or cancel this authorization at any time by providing notice to [Business Name] with 30 (thirty) days notice. If you use [Business Name]‘s services or purchase additional products periodically pursuant to [Business Name]‘s terms, you authorize [Business Name] to debit your bank account periodically. Payments that fall outside the regular debits authorized above will only be debited after your authorization is obtained.

SWIFT

let mandateData = PrimerStripeOptions.MandateData.templateMandate(merchantName: "Business Name")

• you specify the entire body of the mandate:

SWIFT

let mandateData = PrimerStripeOptions.MandateData.fullMandate(text: "... Mandate full text ...")

SWIFT

let settings = PrimerSettings(
  // ...
  paymentMethodOptions: PrimerPaymentMethodOptions(
    stripeOptions: PrimerStripeOptions(
        publishableKey: "your_stripe_publishable_key",
        mandateData: mandateData),
  )
  // ...
)

Proceed with the SDK initialization:

SWIFT

Primer.shared.configure(settings: settings, delegate: self)

Show Universal Checkout

ACH via Stripe payment method is automatically presented to the customer when calling Primer.shared.showUniversalCheckout(clientToken: self.clientToken).

SWIFT

class MyViewController: UIViewController, PrimerDelegate {
    func startUniversalCheckout() {
        Primer.shared.showUniversalCheckout(clientToken: self.clientToken)
    }
}

Show Universal Checkout

ACH via Stripe is automatically presented to the customer when calling Primer.shared.showUniversalCheckout.

SWIFT

class MyViewController: UIViewController {
  func startUniversalCheckout() {
    Primer.shared.showUniversalCheckout(clientToken: self.clientToken)
  }
}

Customization

Check the customization guide to learn how to customize payment method buttons.

Android

Pre-requisites

Pass device info and payment type when creating the client session ACH via Stripe requires that a mandate is accepted before the payment is completed. Mandates that are accepted online require IP address and user-agent of the device that the payment is made from.

Specify this information when creating the client session, otherwise payments will remain in Pending state.

JSON

{
  ...
  customer: {
    emailAddress: '...',
    ...
  },
  "metadata": {
    "deviceInfo": {
      "ipAddress": "127.0.0.1", // IP address of the device accepting the mandate
      "userAgent": "Mozilla/5.0" // user-agent of the device accepting the mandate
    }
  }
  ...
}

Define the Primer Stripe dependency

Amend the dependencies section of your app’s build.gradle to include Primer’s stripe-android library:

KOTLIN

dependencies {
  /* Other dependencies... */
  // Use the latest version available (https://central.sonatype.com/search?q=primer&namespace=io.primer)
  implementation "io.primer:stripe-android:x.y.z"
}

Define the Stripe publishable key and mandate information

It is important that you specify your Stripe publishable key along with mandate information when instantiating PrimerSettings, otherwise you’ll encounter errors at app runtime.

ACH via Stripe requires that a mandate is displayed before the payment is completed. This mandate will display automatically once a bank account is chosen.

The drop-in implementation provides two ways for customizing the mandate.

• you specify only your business’s name and the SDK will use a predefined template: By clicking Accept, you authorize [Business Name] to debit the bank selected bank for any amount owed for charges arising from your use of [Business Name]‘s services and/or purchase of products from [Business Name], pursuant to [Business Name]‘s website and terms, until this authorization is revoked. You may amend or cancel this authorization at any time by providing notice to [Business Name] with 30 (thirty) days notice. If you use [Business Name]‘s services or purchase additional products periodically pursuant to [Business Name]‘s terms, you authorize [Business Name] to debit your bank account periodically. Payments that fall outside the regular debits authorized above will only be debited after your authorization is obtained.

KOTLIN

val mandateData = PrimerStripeOptions.MandateData.TemplateMandateData("Business Name")

• you specify the entire body of the mandate as a string resource:

KOTLIN

// 'full_mandate_data' is a custom string resource defined by your app. The naming is used as an example here, it can be replaced with any suitable identifier.
val mandateData = PrimerStripeOptions.MandateData.FullMandateData(R.string.full_mandate_data)

• you specify the entire body of the mandate as a string:

KOTLIN

val mandateData = PrimerStripeOptions.MandateData.FullMandateStringData("full mandate text")

KOTLIN

val settings = PrimerSettings(
  // ...
  paymentMethodOptions = PrimerPaymentMethodOptions(
    stripeOptions = PrimerStripeOptions(
        mandateData = mandateData,
        publishableKey = "your_stripe_publishable_key"
    )
  )
  // ...
)

Proceed with the SDK initialization:

KOTLIN

Primer.instance.configure(settings, listener)

The default onFailed implementation of PrimerCheckoutListener will emit unlocalized error messages provided by the Stripe SDK. You’re welcome to override the function to suit your specific needs.

For a more comprehensive understanding, refer to the documentation available for the PrimerCheckoutListener interface and to the Initialize Universal Checkout section in the Get started guide.

Show Universal Checkout

ACH via Stripe is automatically presented to the customer when calling Primer.instance.showUniversalCheckout.

KOTLIN

class CheckoutActivity : AppCompatActivity() {
  private fun setupObservers() {
    viewModel.clientToken.observe(this) { clientToken ->
      showUniversalCheckout(clientToken)
    }
  }
  private fun showUniversalCheckout(clientToken: String) {
    Primer.instance.showUniversalCheckout(this, clientToken)
  }
}

Show Universal Checkout

ACH via Stripe is automatically presented to the customer when calling Primer.instance.showUniversalCheckout.

KOTLIN

class CheckoutActivity : AppCompatActivity() {
  private fun setupObservers() {
    viewModel.clientToken.observe(this) { clientToken ->
      showUniversalCheckout(clientToken)
    }
  }
  private fun showUniversalCheckout(clientToken: String) {
    Primer.instance.showUniversalCheckout(this, clientToken)
  }
}

Customization

Check the customization guide to learn how to customize payment method buttons.

React Native

Pre-requisites

Pass device info and payment type when creating the client session
ACH via Stripe requires that a mandate is accepted before the payment is completed. Mandates that are accepted online require IP address and user-agent of the device that the payment is made from.

Specify this information when creating the client session, otherwise payments will remain in Pending state.

JSON

{
  ...
  customer: {
    emailAddress: '...',
    ...
  },
  "metadata": {
    "deviceInfo": {
      "ipAddress": "127.0.0.1", // IP address of the device accepting the mandate
      "userAgent": "Mozilla/5.0" // user-agent of the device accepting the mandate
    }
  }
  ...
}

Define the Primer Stripe dependency

Android
Amend the dependencies section of your app’s build.gradle to include Primer’s stripe-android library:

JS

dependencies {
  /* Other dependencies... */
  // Use the latest version available (https://central.sonatype.com/search?q=primer&namespace=io.primer)
  implementation "io.primer:stripe-android:x.y.z"
}

iOS

Add the dependency to your Podfile:

RUBY

/* ... other dependencies **/
pod 'PrimerStripeSDK', 'x.y.z'

Define the Stripe publishable key and mandate information It is important that you specify your Stripe publishable key along with mandate information when instantiating PrimerSettings, otherwise you’ll encounter errors at app runtime.

ACH via Stripe requires that a mandate is displayed before the payment is completed. This mandate will display automatically once a bank account is chosen.

The drop-in implementation provides two ways for customizing the mandate.

• you specify only your business’s name and the SDK will use a predefined template: By clicking Accept, you authorize [Business Name] to debit the selected bank account for any amount owed for charges arising from your use of [Business Name]‘s services and/or purchase of products from [Business Name], pursuant to [Business Name]‘s website and terms, until this authorization is revoked. You may amend or cancel this authorization at any time by providing notice to [Business Name] with 30 (thirty) days notice. If you use [Business Name]‘s services or purchase additional products periodically pursuant to [Business Name]‘s terms, you authorize [Business Name] to debit your bank account periodically. Payments that fall outside the regular debits authorized above will only be debited after your authorization is obtained.

JS

let settings: PrimerSettings = {
    ...
    paymentMethodOptions: {
        stripeOptions: {
            publishableKey: "your_stripe_publishable_key",
            mandateData: {
                merchantName: "Business Name"
            }
        },
        ...
    }
    ...
}

• you specify the entire body of the mandate: Use fullMandateText to specify the full mandate text for both iOS and Android. On Android, fullMandateStringResourceName will be used instead if provided.

JS

// 'full_mandate_resource_key' is the name/key of a string resource defined on the Android side of your app. 
// The naming is used as an example here, it can be replaced with any suitable identifier.

let settings: PrimerSettings = {
    ...
    paymentMethodOptions: {
        stripeOptions: {
            publishableKey: "your_stripe_publishable_key",
            mandateData: {
                    fullMandateText: "full mandate text",
                fullMandateStringResourceName: "full_mandate_string_resource_name" // Android only
            }
        },
        ...
    }
    ...
}

Proceed with the SDK initialization:

JS

await Primer.configure(settings);

The default onError listener will emit unlocalized error messages provided by the Stripe SDK. You’re welcome to override the function to suit your specific needs.

For a more comprehensive understanding, refer to the configuration documentation and to the Initialize Universal Checkout section in the Get started guide.

Show Universal Checkout
ACH via Stripe is automatically presented to the customer when calling Primer.showUniversalCheckout.

JS

await Primer.showUniversalCheckout(clientToken);

Customization
Check the customization guide to learn how to customize Universal Checkout.

Go live
You don’t need to do anything particular to go live — just make sure to use production credentials.

Show Universal Checkout

ACH via Stripe is automatically presented to the customer when calling Primer.showUniversalCheckout.

Typescript

const CheckoutScreen = async (props: any) => {
  const onUniversalCheckoutButtonTapped = async () => {
    try {
      await Primer.showUniversalCheckout(clientToken)
    } catch (err) {
      // handle error
    }
  }
}

Customization

Check the customization guide to learn how to customize payment method buttons.

Vaulting

When creating client session, vaultOnAgreement flag should be passed, along with paymentType:

JSX

"paymentMethod": {
    "vaultOnAgreement": true,
    "paymentType": "FIRST_PAYMENT"
  }

Note that the vaultOnAgreement flag is supported starting with API version 2.4.

In order to vault ACH via Stripe accounts, pass the following data in the Client Session:

Parameter Name	Required	Description
customerId	✓	A unique identifier for your customer

Web

Minimum version of Web SDK: 2.47.0.

ACH via Stripe payment tokens can be vaulted automatically on successful agreement if the vaultOnAgreement flag is turned on when creating the client session.

JSX

"paymentMethod": {
    "vaultOnAgreement": true,
    "paymentType": "FIRST_PAYMENT"
  }

iOS

Minimum version of iOS SDK: 2.33.0.

ACH via Stripe payment tokens can be vaulted automatically on successful agreement if the vaultOnAgreement flag is turned on when creating the client session.

JSX

"paymentMethod": {
    "vaultOnAgreement": true,
    "paymentType": "FIRST_PAYMENT"
  }

Android

Minimum version of iOS SDK: 2.33.0.

ACH via Stripe payment tokens can be vaulted automatically on successful agreement if the vaultOnAgreement flag is turned on when creating the client session.

JSX

"paymentMethod": {
    "vaultOnAgreement": true,
    "paymentType": "FIRST_PAYMENT"
  }

React Native

Minimum version of React Native SDK: 2.28.0.

ACH via Stripe payment tokens can be vaulted automatically on successful agreement if the vaultOnAgreement flag is turned on when creating the client session.

JSX

"paymentMethod": {
    "vaultOnAgreement": true,
    "paymentType": "FIRST_PAYMENT"
  }

Test

You can test payments using USD as the currency.

Sandbox testing

• After selecting the payment method button in the Checkout, the page will navigate to a form
• After you complete the form, the Stripe pop-up will appear
• After finishing the steps inside the Stripe pop-up, the user will be taken back to the Checkout to confirm / decline mandate
• At the end of this flow, the payment status will be first in the Primer Dashboard and depending on the user actions or external factors, like insufficient funds in the bank account, it will be either , or for successful completion in Primer Dashboard
• To simulate the receiving of funds and transition the payment to , you can choose in the Stripe pop-up: Test Institution and Success account in the next screen. Next you will be taken back to Checkout to confirm the mandate. Primer will receive a webhook and subsequently update the payment to .

Go Live

You don’t need to do anything particular to go live — just make sure to use production credentials.