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

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

ACH Feature Overview

Recurly offers ACH bank payments through our integration with Check Commerce, a payment gateway that specializes in ACH payments. 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.

  • This feature is only available for merchants located in the United States
  • ACH is included in the Enterprise and Professional plans at no additional cost; Check Commerce fees will apply
  • Merchants not currently on Enterprise or Professional plan can try out ACH on a sandbox site before upgrading

Check Commerce

Check Commerce is a gateway that specifically accepts ACH payments. Recurly will not be able to work with any other gateways that support ACH payments at this time. In order to process ACH payments, merchants will need to get a Check Commerce account via Recurly. The ACH application process generally takes 3-4 days with submittal of required documents.

  • Merchants must be located in the United States to apply
  • Merchants must have a chargeback rate of 0.5% or lower
  • Standard Check Commerce accounts are limited to $5,000/transaction, but merchants may be approved for higher limits
  • If approved for a higher limit, you will receive two Check Commerce accounts, one for $5,000 or less transactions and one for above $5,000 transactions
  • The standard $5,000/transaction limit Check Commerce account charges $1/transaction, higher limit accounts will include a percentage of revenue as well. These are Check Commerce fees; Recurly does not charge any transaction or revenue fees for ACH transactions.
  • The Check Commerce application will require you to provide: a voided check, driver's license, articles of incorporation and web screenshots of your check out flow with the required disclaimers. Additional requirements apply if the merchant has one or more Principal who is based in Canada (e.g. copy of Principal's passport).

PRO TIP: Once you request an application from Check Commerce following the instructions below, we suggest you gather the above documents while you wait to be contacted by Check Commerce. While in the application process, you can start testing ACH on a sandbox Recurly site in order to get your integration ready. You do not need a Check Commerce account to test on a sandbox site.

Apply for an Account

To apply for a Check Commerce account, log into Recurly and visit the Payment Gateways page.

  1. Click on the "Add a New Gateway" button at the top right of the Payment Gateways page.
  2. Select the Check Commerce option at the bottom of the page. If your Site Settings country is not in the United States, you will not see the Check Commerce option and will not be able to use the payment gateway.
  3. Once you have selected Check Commerce, click the "Request an Account" button.
  4. You will be redirected to Check Commerce's online application for a new account.

Connect your Account to Recurly

Once you are approved for a Check Commerce account and have been given your credentials, use them to connect your account to Recurly.

  1. Make sure you have subscribed to Recurly's Enterprise or Professional plan and have moved into production mode.
  2. Visit the Payment Gateways page in your Recurly Admin and click "Enter Credentials" next to your Check Commerce application status.
  3. Enter your Check Commerce Merchant ID (a numeric string) and Password.
  4. Make sure Check Commerce is enabled for new transactions.
  5. Click "Add Payment Gateway".
  6. You will see that Check Commerce has been added to our list of Production Gateways and has a status of enabled.

Now that you have Check Commerce enabled for ACH, you will need to configure your payment forms to include the "Bank Account" option.

Adding Multiple Check Commerce Accounts

If you have two Check Commerce accounts, go ahead and add the second account by visiting the "Add Payment Gateways" page and selecting Check Commerce a second time. Once both accounts are added, you will be able to tell the difference between the account by the "Transaction Limit" displayed on the Payment Gateways page. If you ever need to know your account number, just click Edit.

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, adding a Check Commerce account will automatically enable a Bank Account tab on your sign-up pages. If you do not wish to have the Bank Account tab on your sign-up pages, disable "Payment Pages" under the "ACH" section on the Hosted Page Settings in your Recurly site. Since Bank Account sign-ups will start the subscription immediately, before we get a success response from Check Commerce, you may want to limit the Bank Account option to your Hosted Account Management Invoice page to avoid a large number of sign-ups that may result in declines.

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 Check Commerce 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 with Check Commerce. 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, Check Commerce 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 Check Commerce, marking the invoice to stop collecting will not stop the transaction processing. You will need to void the transaction (if possible) or 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 Check Commerce 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.

Check Commerce does have its own functionality for payment retries. Recurly recommends disabling this feature.

Refunds and Voids

Refund attempts will generate an invoice immediately, but processing takes additional time. If Check Commerce decides to decline the refund 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

CheckCommerce sets a maximum amount for each ACH payment. If any single ACH payment exceeds this amount, CheckCommerce will decline the transaction. To change your threshold, please contact CheckCommerce. Once CheckCommerce has updated your threshold, please:

  1. Return to your CheckCommerce gateway configurations page in Recurly
  2. Navigate to where you can edit the gateway credentials
  3. Save your gateway credentials again. This will update your threshold in Recurly.

When you save the credentials again in Recurly, your credentials will be updated with the new thresholds from Check Commerce. If you continue to encounter issues with your threshold, please contact Recurly Support.

ACH Bank Payments

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