ACH payments are online payments that move funds to a merchant from a user's bank account. ACH validation is the process of validating a user's bank account to help avoid data entry errors and reduce fraud when a user wants to pay by bank. In the Rainforest ecosystem, we refer to this type of payment as a Validated ACH.

Rainforest utilizes a third-party partner, Plaid, for real-time validation by requesting the user authenticate into their online bank account to collect the bank account information. This ensures the bank account is active and the user was able to successfully authenticate with their bank account credentials.

Configure the merchant

Sandbox

In the Rainforest Sandbox environment, the Validated ACH Payment flow is automatically enabled. This guide will walk you through how to configure your Payment Component to accept Validated ACH payments.

Production

In the Rainforest Production environment, Rainforest will need to enable this feature for your platform and merchants. Once you're ready to enable in Production, reach out to [email protected] and Rainforest will help your with your merchant's billing profile setup and enabling ACH Validation for your merchants.

Set the ACH validation fee

An ACH validation fee is applied when storing the payment method, which occurs when using the Payment Component to process a payment or store a payment method. ACH validation fees can be passed onto the merchant via the merchant billing profile. See the billing merchants section for additional information on how the ACH validation fee is billed to the merchant.

We can update the ACH validation fee on an existing billing profile that currently has the ACH validation fee set to $0. Or head over to the Rainforest Platform Portal to create a new billing profile with an ACH validation fee.

Enable the merchant

Let us know if you'd like to enable the Validated ACH payment method option for a specific merchant or for all your merchants and any merchants onboarded going forward.

The payment component must still be configured to display the Validated ACH payment method option to your user.

Configure the payment component

Plaid compatibility

If you use a Content Security Policy (CSP), you will need to add the following directives to allow Plaid, the third-party partner, to run on your page:

default-src https://cdn.plaid.com/
script-src https://cdn.plaid.com/
frame-src https://cdn.plaid.com/
connect-src https://production.plaid.com/

Enable the Validated ACH method

When rendering the Payment Component, add VALIDATED_ACH to the list of allowed-methods:

  <rainforest-payment
    session-key='REPLACE_ME'
    payin-config-id='REPLACE_ME'
-   allowed-methods="CARD,ACH"
+   allowed-methods='CARD,ACH,VALIDATED_ACH'
  ></rainforest-payment>

Rainforest will display the Validated ACH payment method option, if it is enabled and configured for the merchant. If you do not see the Validated ACH payment method, reach out to support to confirm the merchant is enabled.

Customize the component

Head over to the Component Studio for more attributes you can provide to customize the component's appearance and behavior.

Embedded

The default display is an embedded search. After choosing their bank, the Plaid modal will popup for the user to authenticate with their bank account. When Validated ACH is an available payment method option, it will be preferred over entering bank account details manually.

Button

The other display option is a "Connect with bank login" button that will popup the Plaid modal for the user to authenticate with their bank account.

When rendering the Payment Component, set the validated-ach-view prop to BUTTON:

  <rainforest-payment
    session-key='REPLACE_ME'
    payin-config-id='REPLACE_ME'
    allowed-methods='CARD,ACH,VALIDATED_ACH'
+   validated-ach-view='BUTTON'
  ></rainforest-payment>

Customize the Connect with bank login button

By default, the "Connect with bank login" button color will be the inverse of the style-button-color prop. You can customize the button with the following props:

• style-secondary-button-color - sets the fill color of the button
• style-secondary-button-font-color - sets the font color within the button

Default account purpose

The account purpose will be set to Personal by default when rendering the Payment Component. To change the default to Business, add the field-defaults prop and set it to the following:

  <rainforest-payment
    session-key='REPLACE_ME'
    payin-config-id='REPLACE_ME'
    allowed-methods='CARD,ACH,VALIDATED_ACH'
+   field-defaults='{"ach": {"account_holder_type": "BUSINESS"}}'
  ></rainforest-payment>

Event listeners

If Validated ACH is requested via the allowed-methods prop, we'll let you know if it is supported and available for the specified merchant via events.

The loaded event will return a payload in the following format:

type ValidatedACHPartner = 'PLAID';

type LoadedPayload = {
    apple_pay: {
        is_supported: boolean;
    };
    validated_ach: {
        partner: Nullable<ValidatedACHPartner>;
        is_supported: boolean;
    };
};

Listen to this event and parse the event data to know if Validated ACH is supported:

const component = document.getElementById('payment-component');
component.addEventListener('loaded', function (data) {
    if (data.detail[0].validated_ach.is_supported) {
        console.log('Validated ACH is supported!');
    }
});

Handle the new payment method type

Payments processed via Validated ACH will be represented in the API as a separate type of payment method.

Check if you have any code that looks at a Rainforest Payin or PaymentMethod and gets data from the ach sub-object. For a Validated ACH payment, the following will be different:

• method_type will be PLAID_ACH
• ach will be null
• plaid_ach will be populated with relevant information on the payment method

{
  // ...
  "method_type": "PLAID_ACH",
  "ach": null,
  "plaid_ach": {
    "account_number_last_4": "0000",
    "routing_number": "091000022",
    "bank_name": "US BANK",
    "account_type": "CHECKING",
    "account_holder_type": "PERSONAL"
  }
}

Validated ACH payments in reports

There will be two indicators in reporting if a payment was processed with a Validated ACH payment method.

1. The payment method icon includes a check mark indicating it was validated.
2. The Related info section includes an "ACH Validation" field that indicates the third-party partner, Plaid, utilized for validation.

Saving a payment method

To support the Validated ACH payment method option when saving a payment method with the Payment Component, you need to set the billable_merchant_id when creating a payment method config. This is required for billing if the ACH validation fee should be passed on to the merchant. The payment method can still be utilized across merchants on your platform after it's been stored.

This field is required on the Rainforest API version 2024-10-16. If your integration is on the latest version, there are no changes you need to make.

⬆️

Upgrade your API version

If your integration is not on the latest API version, 2024-10-16, we highly encourage you to upgrade to get access to new features Rainforest has released. However, the Validated ACH payment method can be supported on earlier versions, but requires the billable_merchant_id field to be set when creating a payment method config.

Billing merchants

When a Validated ACH payment method is created, there is a one time ACH validation fee that can be passed onto the merchant via the merchant billing profile. After this the Validated ACH payment method can be used for recurring payments without an additional fee for validation.

In the merchant's daily funding deposit, an adjustment will be included for all Validated ACH payment methods created the day before with an 11pm daily cutoff.

For example, the merchant's deposit on December 19, 2024 would include an adjustment for the ACH payment methods created between December 17th 11:00pm ET and December 18th 11:00pm ET.