The Reference Docs Developer Hub

Welcome to the Reference Docs developer hub. You'll find comprehensive guides and documentation to help you start working with Reference Docs as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

ACH Bank Payments (US only)

ACH is a payment method supported by Recurly. This payment method allows a customer to pay their invoices via their bank account directly.

ACH Feature Overview

ACH payments allow you to directly debit and credit a customer's bank account, without having to go through credit card processors or deal with physical checks.

  • ACH is a bank payment method available in the United States. It is distinct from other bank payment methods available in other regions or countries, such as SEPA (EU), BACS (UK), and BECS (AU).
  • This feature is only available for merchants domiciled in the United States.
  • The ACH feature is included in the Professional, Elite, and Enterprise plans and transactions count towards the dollar amount of the transactions processed.
  • Merchants not currently on Professional, Elite, or Enterprise plans can try ACH on a sandbox site before upgrading.

Adyen ACH Gateway Integration

Recurly offers support for ACH transactions via Adyen. To learn more about ACH payments, visit our ACH Bank Payments docs page.

To set up your ACH gateway, add the 'Adyen ACH' gateway from the "Add Payment Gateway" page, and complete the process for adding a gateway outlined here.

Also ensure that the configuration outlined below is completed in order to properly process ACH transactions.

  1. Configure the "report credentials" (how to)
  2. Subscribe to the Payment Accounting Report (how to)
  3. Ensure that your configuration in Adyen sets transactions for "immediate capture".

About ACH Payments

Site Configuration for Hosted Pages

If you are going to include a Bank Account tab on your Hosted Payment Pages (sign-up pages) or your Hosted Account Management Invoice pages, you will need to visit your Hosted Page Settings in your Recurly site.

Hosted Payment Pages

If you have Hosted Payment Pages turned on, you can accept ACH payments via our Hosted Payment Pages. Ensure you have enabled ACH and USD on your site.

Hosted Account Management

The Hosted Account Management Hosted Invoice page has the option to turn on Online Payments. This allows your customers who have received manual invoices to pay those invoices online with an automatic method. To enable the Bank Account option:

  • Enable "Pay invoices online" under Customer Options on the Hosted Page Settings tab in your Recurly Admin
  • Under the "ACH" section below Customer Options, enable "Account Management"
  • To see the pay button, create a manual invoice and click the "Hosted Invoice" button at the top right of the invoice page
  • If "Pay invoices online", "Account Management" and ACH are enabled, the Bank Account option will automatically show up as an option for the "Make A Payment" button on the hosted invoice page.

Please Note: Since our ACH feature only supports merchants/customers in the US, the option to pay an invoice online using ACH will only be available if the invoice is using a US address.

Payment Authorization

ACH is regulated by an organization called NACHA. Customers must authorize all payments and any future recurring collections. An authorization must include:

  • Date of purchase
  • Amount of purchase
  • Customer name
  • Account number
  • Routing number and bank name
  • Authorization language for the payment and whether there are renewals
  • Authorization language to attempt additional collections if the first transaction fails
  • Language letting the customer know that if they need to cancel, they must contact the merchant by a certain number of days before the payment and how they should contact the merchant.

Merchants have a responsibility to keep a customer's authorization of an ACH payment for two years from the final payment. Recurly uses "WEB" ACH transactions, which allow the authorization proof to be login and purchase records, along with screenshots of your checkout flow where the disclaimer language was visible.

ACH Statuses

Processing, a common status for an ACH invoice, maps to lifecycle of an ACH transaction. With automated credit card payments Recurly usually receives an immediate success or decline, but ACH has a time delay for while a transaction completes. During this status, the invoice is awaiting payment confirmation. Unlike an "open" invoice, this invoice is actively working towards completion and requires no merchant or customer action.

There are three other common states for ACH transactions:
Pending is an internal state indicating that a transaction has been created. It's a very short state that moves into Scheduled. If an invoice is in the Pending state for any length of time please contact Recurly support. One common reason for an ACH transaction to remain in a pending state is if the invoice contains more than 100 line items. If this is the case, please contact Recurly Support for assistance.

A transaction moves from Pending into the Scheduled state. This transaction is being validated and scheduled. A merchant may be able to void a transaction in this state (note: voids for ACH are only supported in the UI, not the API)

Once validated and queued, the transaction moves into the Processing state. During this state, the gateway is working with the banking system to settle funds. The transaction cannot be modified during this state.

Please note: Once a transaction has been submitted to the ACH gateway, marking the invoice to stop collecting will not stop the transaction processing. You will need to refund the transaction after it's successfully processed.

Email Communication

When an ACH payment is initiated, the customer will receive the Payment Confirmation email with text stating that the payment will take 4 business days to process. If the transaction declines, the customer will get the Payment Declined email. If the transaction succeeds, the customer will not receive another email.

When an ACH refund is initiated, the customer will receive the Payment Refunded email with text stating that the payment refund will take 4 business days to process. If the refund transaction declines or is successful, the customer will not receive another email.

Webhooks

Relevant webhooks have been added in support of ACH. Please see Webhooks for full code samples.

  • Invoice State - processing_invoice_notification
  • Payment State - scheduled_payment_notification
  • Payment State - processing_payment_notification

API

API v2 now supports ACH bank account billing information. Please see our billing info documentation for more information.

Recurly.js

Recurly.js v3 functionality has been added in support for ACH. Please see our Recurly.js documentation for more information.

Dunning

While an ACH invoice is in a past due state, it will align with the Automatic Collection Dunning settings. The dunning cycle will not be reset with customer attempts to update billing information. Due to the longer processing times for ACH payments, Recurly recommends a review of dunning length when adding this feature.

Retries

Unlike credit card payments, Recurly will not automatically try recycling ACH payments due to the fees assessed by the gateway for each attempt. Merchants have the ability to retry an ACH transaction via the admin console 2 additional times, for a maximum of 3 transaction attempts allowed by NACHA. If a customer successfully updates their billing info, Recurly will attempt collection of past due invoices (both credit card and ACH) and the attempt counter will reset.

Refunds and Voids

Refund attempts will generate an invoice immediately, but processing takes additional time. If a refund is declined during processing, the original refund invoice will be marked as failed and the merchant may attempt a refund again. A Payment Refunded email will be sent as soon as a refund is initiated and states that the refund will take 4 business days to process. If the refund declines, the customer will not get another email.

ACH transactions in a scheduled state can be voided. The 'scheduled' state means that the transaction has not yet been sent to the banking system. Once the transaction is sent to the banking system, the transaction state will change to 'processing' and can no longer be voided or refunded. ACH transactions can only be voided in the UI, not the API.

When an ACH payment is voided, the related invoice will move to a Past Due state. If an ACH refund is voided, the related refund invoice will move to a Failed state, and a new refund can be issued from the original payment invoice. In both cases, the customer will not be emailed.

Chargebacks

If a transaction reports a chargeback, Recurly will keep the original invoice and transaction as paid/successful, but create a refund invoice with a new transaction reflecting the chargeback. The invoice will have a note indicating the refund reason was due to a chargeback (the transaction will be Chargeback). You can also query for Chargeback state in the transaction export.

For More Information

Recurly is using the SEC code WEB implementation. Recurly does not maintain responsibility for any merchant rules, regulations, communications, and disclaimers imposed by NACHA.org.

Sandbox Testing

To test ACH in a Recurly sandbox site, please use the following test credentials with the Recurly Test Gateway:

  • Routing #: 123456780
  • Account #: 111111111 (Success)
  • Account #: 111111112 (Declined)
  • Account #: 111111113 (Declined)
  • Account #: 111111114 (Will first be successful and then will issue a chargeback)
  • Account #: 111111115 (If refunded, will be a successful refund)
  • Account #: 111111116 (If refunded, will be a declined refund)

Updating your per-check limit

Most ACH gateways set a maximum amount for each ACH payment. If any single ACH payment exceeds this amount, the gateway will decline the transaction. To change your threshold, please contact your gateway.

After your threshold has been updated with your gateway, if you continue to encounter issues with your threshold, please contact Recurly Support.

Updated 19 days ago

ACH Bank Payments (US only)


ACH is a payment method supported by Recurly. This payment method allows a customer to pay their invoices via their bank account directly.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.