Cinchoo NACHA

• Download source code
• Download binary

1. Introduction

ChoETL.NACHA is an open source NACHA driver for .NET. It is a code based library for reading and generating NACHA formatted files in .NET environment. Because it can be tedious and error prone to generate large fixed width documents like ACH files, I've created and open sourced Cinchoo NACHA.

The Automatic Clearing House (ACH) network is the primary way money moves electronically through the banking system today. It uses NACHA file format for the movement of money in the USA.

Features

• Follows standard NACHA specifications
• Handles most of the house keeping calculation work automatically
• Detailed and robust error handling, allowing you to quickly find and fix problems

2. Requirement

Some basic understanding of ACH/NACHA specifications. This framework library is written in C# using .NET 4.5 / .NET Core Frameworks.

Install NACHA library via Package Manager Console using Nuget Command based on the .NET environment:

.NET Framework

install-package ChoETL.NACHA

.NET Core

install-package ChoETL.NACHA.NETStandard

3. Using the Code

3.1 What Is NACHA File?

An ACH file is nothing more than a file with multiple lines of ASCII text, each line 94 characters in length. A line is a called a "record".

There are 5 main record types in an ACH file:

1. File Header Record
2. Batch Header Record
3. PPD Entry Detail Record
4. Batch Control Record
5. File Control Record

For more details about it, read the NACHA specs.

3.2 Read ACH File

If you have an ACH returns file, you can load with Cinchoo NACHA library with few lines of code.

Listing 3.2.1 NACHA reader sample

foreach (var r in new ChoNACHAReader("20151027B0000327P018CHK.ACH"))
    Console.WriteLine(r.ToStringEx());

In the above, create an object of ChoNACHAReader class and pass the ACH file. This object returns the list of NACHA records to iterate through.

UPDATE: If the ACH file contains filler records after file control record, the reader will discard them now.

In the below sample ACH file, the last 4 records will not be read by the NACHA reader.

Listing 3.2.2 NACHA sample file

101123456789 123456789 1702170810A094101PNC Bank               PNC Bank               Internal
5200Microsoft Inc.                      123456789 PPD                         1123456780000001
82000000000000000000000000000000000000000000123456789                          123456780000001
5200Microsoft Inc.                      123456789 PPD                         1123456780000002
82000000000000000000000000000000000000000000123456789                          123456780000002
9000002000001000000000000000000000000000000000000000000                                       
9999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999
9999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999
9999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999
9999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999

3.3 Generate ACH File

If you want to generate ACH file, you can do so with Cinchoo NACHA library with few lines of code.

Listing 3.3.1 NACHA writer sample

ChoNACHAConfiguration config = new ChoNACHAConfiguration();
config.DestinationBankRoutingNumber = "123456789";
config.OriginatingCompanyId = "123456789";
config.DestinationBankName = "PNC Bank";
config.OriginatingCompanyName = "Microsoft Inc.";
config.ReferenceCode = "Internal Use Only.";
config.BlockingFactor = 10;

using (var nachaWriter = new ChoNACHAWriter("ACH.txt", config))
{
    using (var bw1 = nachaWriter.CreateBatch(200))
    {
        using (var entry1 = bw1.CreateDebitEntryDetail
              (20, "123456789", "1313131313", 22.505M, 
              "ID Number", "ID Name", "Desc Data"))
        {
            entry1.CreateAddendaRecord("Monthly bill");
        }
        using (var entry2 = bw1.CreateCreditEntryDetail
              (20, "123456789", "1313131313", 22.505M, 
              "ID Number", "ID Name", "Desc Data"))
        {

        }
    }
    using (var bw2 = nachaWriter.CreateBatch(200))
    {
    }
}

In the above, we create ChoNACHAConfiguration object and assign basic and necessary bank related information to it. Instantiate ChoNACHWriter object with ACH file name along with configuration object to start the generation process.

Then, you can create number of NACHA batches using ChoNACHAWriter.CreateBatch() method sequentially. Followed by create either Debit or Credit Entry Detail record using ChoNACHABatchWriter object. Optionally, you can create addenda records using ChoNACHAEntryDetailWriter object.

Once done, the ACH file will be generated in no time.

3.4 ChoNACHAConfiguration 

Here are the NACHA configuration available to configure while reading / writing NACHA files using Cinchoo NACHA.

• FieldValueTrimOption - Option to trim the values while parsing. Possible values are None, TrimStart, TrimEnd, Trim.
• PriorityCode - The lower the number, the higher processing priority. Currently, only 01 is used
• DestinationBankRoutingNumber - Number that identifies the bank site where it process the files.
• TurnOffDestinationBankRoutingNumber
• OriginatingCompanyId - is a number that identifyies entities, called originators, collecting payments.
• TurnOffOriginatingCompanyIdValidation
• FileIDModifier - Unique file identifier. Code to distinguish among multiple input files.
• BlockingFactor - a non-zero value, the NACHAWriter will generate the file with FileControl FILLER records in the last incomplete block.
• FormatCode - Currently there is only one code. Enter 1.
• DestinationBankName - Destination bank name.
• OriginatingCompanyName - Originating bank name.
• Reserved - reserved character used to File Trailer Record's (Type 9) Reserved field.
• ReferenceCode - Optional field you may use to describe input file for internal accounting purposes.
• BatchNumber - Number batches sequentially.
• BatchNumberGenerator - Custom batch number generator.
• EntryDetailTraceSource - Source of TraceNumber in Entry Detail Record (DestinationBankRoutingNumber/OriginatingDFI) 

3.5 BlockingFactor Usage Sample  

If the ChoNACHAConfiguration.BlockingFactor is specified with non-zero value, the NACHAWriter will generate the file with FileControl FILLER records in the last incomplete block.

The sample below shows the ACH output file with BlockingFactor of 10.

Listing 3.3.2 NACHA file output with filler records

101123456789 123456789 1702170810A094101PNC Bank               PNC Bank               Internal
5200Microsoft Inc.                      123456789 PPD                         1123456780000001
82000000000000000000000000000000000000000000123456789                          123456780000001
5200Microsoft Inc.                      123456789 PPD                         1123456780000002
82000000000000000000000000000000000000000000123456789                          123456780000002
9000002000001000000000000000000000000000000000000000000                                       
9999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999
9999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999
9999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999
9999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999999

If the ChoNACHAConfiguration.BlockingFactor is specified with zero value, the NACHAWriter will NOT generate the file with FileControl FILLER records in the last incomplete block.

Listing 3.3.3 NACHA file output without filler records

101123456789 123456789 1702170810A094101PNC Bank               PNC Bank               Internal
5200Microsoft Inc.                      123456789 PPD                         1123456780000001
82000000000000000000000000000000000000000000123456789                          123456780000001
5200Microsoft Inc.                      123456789 PPD                         1123456780000002
82000000000000000000000000000000000000000000123456789                          123456780000002
9000002000001000000000000000000000000000000000000000000