Cinchoo NACHA is an open source NACHA driver for .NET. It is a code based library for parsing / writing NACHA files using .NET.
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
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:
- File Header Record
- Batch Header Record
- PPD Entry Detail Record
- Batch Control Record
- 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