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. Fill out your User ID 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.

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

The ACH payment method includes two applicable email templates in Recurly: Payment Processing and Refunds Processing. Be sure to enable these in your Email Settings (these email templates are disabled by default).

Payment Processing

Once enabled, this email will be sent to the customer when their invoice goes into a processing state. This email acts as the customer's authorization receipt and let's the customer know that their ACH payment has been received and is in progress.

Refund Processing

Once enabled, this email will be sent to the customer when you issue a refund and the refund invoice goes into a processing state. This email let's the customer know that they are receiving a refunds and it is in progress.

Other Email Updates

We have updated a few of the existing email templates to better support ACH payments. Please reset or update these templates if they are currently customized.

  • Payment Declined - We updated the subject to no longer be credit card specific.
  • Payment Refunded - We added conditional tags to hide credit card language and display processing time information for ACH.

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 Refund Processing email will be sent as soon as a refund is initiated; the Refund Receipt email is sent when refund is confirmed. Be sure to enable both emails in your Email Settings.

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 and a Payment Voided email will be sent to the customer. 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.

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.