This is a guest blog post written for Kill Bill by Andrew T., a developer at Dwolla. Dwolla’s Access API has been integrated with Kill Bill’s subscription billing platform to provide access to the ACH network. Learn more about the Kill Bill & Dwolla partnership.
At Dwolla, we have spent a lot of time making it as simple as possible to send ACH bank transfers. With one API call, you can initiate a transfer of funds from one of your customer’s bank accounts, into the Dwolla “Account”, and then out to another customer’s bank account.
From a technical perspective, this is accomplished by using Hypertext Application Language (HAL) hyperlinks to describe the source and ultimate destination of the transfer, rather than by sending ACH routing information to our API for every transfer:
{
“_links”:{
“source”:{
“href”:”https://api.dwolla.com/funding-sources/{sender-funding-source-id}”
},
“destination”:{
“href”:”https://api.dwolla.com/funding-sources/{receiver-funding-source-id}”
}
},
“amount”:{
“value”:”12.00″,
“currency”:”USD”
}
}
Have you ever wondered what Dwolla is doing behind the scenes to make the sometimes complicated or confusing ACH network available within a payments API?
First off, what is ACH?
The Automated Clearing House (ACH) is an electronic network that allows originators to transfer money by debiting or crediting U.S. bank accounts. At a high level, an Originating Depository Financial Institution (ODFI) submits a file containing specific instructions to an ACH Operator. These instructions are used to locate the account (routing number, account number, account type, account holder’s name,…) as well as the amount to credit or debit. The ACH Operator uses these instructions to locate the Receiving Depository Financial Institution (RDFI), and the RDFI can then credit or debit the specific bank account.
For example, when a developer uses Dwolla’s Access API to create a bank-to-bank transfer, we first generate a file that contains the information needed to debit the sender’s bank account. Among other things, this information includes the routing number, account number, account type, and the sender’s name. The debit usually clears in 1-3 business days. We then send the information needed to credit the receiver’s account.
Why the delay? There are a few reasons, but one is that ACH is built on the assumption the funds are available in the sender’s account and the instructions to locate the account are correct. This extra time gives RDFIs the ability to issue return codes notifying the ODFI that the entry failed.
As part of our daily operations, we collect all of the transfers our partners have created through our API and construct ACH files using the NACHA file format. Every line of the file has to be exactly 94 characters long, in blocks of 10 (more on this later), and position specific. The files must also be generated and submitted within the different processing windows, as dictated by NACHA– the regulatory body governing the ACH network.
Every ACH file submitted by Dwolla has a specific header, footer, and one or more batches in between these two elements. However, not all batches are the same, there are several different types of batches and each batch has different Standard Entry Codes (WEB, CIE, CCD…). These batches may be limited to only credits, only debits, or may contain both credits and debits. Some batches, like WEB & PPD share the same entry format, but differ when compared to others, like CIE. For example, characters 55-76 are reserved for the individual’s name in a WEB batch, but within a CIE batch those characters are used for the individuals’s ID.
Let’s take a look at what a debit entry contained within a WEB batch would look like:
Character 1 – Record Type: ‘6’ for detail entries
Characters 2-3 – Transaction Code: Type of debit or credit
Characters 4-12 – Receiving DFI Identification – ABA routing number
Characters 13 – 29 – Receiving DFI account number
Characters 30-39 – Amount $12.00 would be represented as 0000001200
Characters 40-54 – Individual Identification Number
Characters 55-76 – Individual’s Name
Characters 77-78 – Discretionary data
Character 79 – Addenda indicator: ‘0’ for no addenda record, ‘1’ if there is one included
Characters 80-94 Trace Number: 80 – 87 identify the ODFI and 88-94 are unique to that entry on the file.
If we pull together what we’ve outlined above, this is is how the API transaction is represented as an ACH record:
627{routing}{accnt} 0000001200 10821103white label customer 0{ODFIid}0000101
This is just one debit entry. Can you imagine what a real ACH file might look like? Multiple batches containing any amount of credits and debits, with a specific number of filler records to ensure the file can be grouped in 10’s. All of this happening multiple times a day to align with the different processing windows.
Why are we sharing this ACH process with you? Using the Kill Bill open-sourced Dwolla plugin gives you a powerful ACH-based subscription service. Whether you’re looking for a means to avoid a homegrown ACH solution, or to alleviate the complexities of an unfamiliar system, we recommend taking a look at the Dwolla/Kill Bill integration.
