CompAnalytics.X9 0.2.0

.NET Framework 4.6.1
dotnet add package CompAnalytics.X9 --version 0.2.0
NuGet\Install-Package CompAnalytics.X9 -Version 0.2.0
This command is intended to be used within the Package Manager Console in Visual Studio, as it uses the NuGet module's version of Install-Package.
<PackageReference Include="CompAnalytics.X9" Version="0.2.0" />
For projects that support PackageReference, copy this XML node into the project file to reference the package.
paket add CompAnalytics.X9 --version 0.2.0
#r "nuget: CompAnalytics.X9, 0.2.0"
#r directive can be used in F# Interactive and Polyglot Notebooks. Copy this into the interactive tool or source code of the script to reference the package.
// Install CompAnalytics.X9 as a Cake Addin
#addin nuget:?package=CompAnalytics.X9&version=0.2.0

// Install CompAnalytics.X9 as a Cake Tool
#tool nuget:?package=CompAnalytics.X9&version=0.2.0


GitHub code size in bytes Nuget version Nuget downloads API Specification

This library contains classes that represent, read, and write binary X9.100-187 image cash letter files used for electronic transmission of checks to/from a bank. It includes tools for reading the files from disk into an X9Document representation that mimics the structure of the file's various records and fields in friendly, interoperable types. X9Documents can also be created from scratch, then written out to the binary X9 format, enabling simple X9 file creation for your .NET environment use case. All types also offer robust type coercion, bounds-checking for each fixed-length field, comparison utilities to ensure equality across files, and informative exception messages when attempting to violate the X9.100-187 specification. The library is being used in production for transmission of millions of dollars by Composable Analytics.


  1. Ryan O'Shea for Composable Analytics, from Oct. 2019 to Jan. 2020.

API Specification

Full public API specifications can be found here.


Full source is available on GitHub. You may encounter problems trying to build as the csproj found the repository is the one we use internally at Composable, so you'll need to manually resolve DLL dependencies for CompAnalytics.* libraries.

Supported Record Types

The following X9 file record types are fully supported for reading and writing.

Record Class Name Record Type Code
File Header Record FileHeaderRecord 01
Cash Letter Header Record CashLetterHeaderRecord 10
Bundle Header Record BundleHeaderRecord 20
Check Detail Record CheckDetailRecord 25
Check Detail Addendum A Record CheckDetailAddendumARecord 26
Return Record ReturnRecord 31
Return Addendum A Record ReturnAddendumARecord 32
Return Addendum B Record ReturnAddendumBRecord 33
Return Addendum D Record ReturnAddendumDRecord 35
Image View Detail Record ImageViewDetailRecord 50
Image View Data Record* ImageViewDataRecord 52
Bundle Trailer Record BundleTrailerRecord 70
Cash Letter Trailer Record CashLetterTrailerRecord 90
File Trailer Record FileTrailerRecord 99

* See Limitations


Reading an X9 File

The following example reads an X9 file from disk and extracts the embedded check images to TIFFs on disk.

string path = @"C:\Temp\sample.x9";
string imageOutDir = @"C:\Temp\SampleCheckImages";
using (Stream x9File = File.OpenRead(path))
using (X9Reader reader = new X9Reader(x9File))
    doc = reader.ReadX9Document();

Authoring an X9Document

Nuget places limits on Readme size. You can see this example at this gist.

Writing an X9 File

This example uses an X9Writer to write the contents of an X9Document to a binary X9 file on disk.

X9Document doc = ...; // create this using example above
string outFilePath = @"C:\Temp\example.x9";
using (X9Writer writer = new X9Writer(doc))
using (MemoryStream byteStream = new MemoryStream(writer.WriteX9Document()))
using (FileStream x9FileStream = File.Create(outFilePath))


This library was originally developed in 2019 during an accounts-receivable automation project undertaken by Composable Analytics, Inc., where the destination institution was JPMorgan Chase. As a result, the library has the following limitations:

  1. Only the X9.100-187 file standard is supported. Specifically, the library was modeled after JPMorgan's Merchant ICL Deposit specifications v4, R7.
  2. Some classes, notably the various classes modeling each type of record in the X9 file (X9Records), contain a method for quickly setting the values of some fields based on a limited set of arguments and populating other fields with JPMorgan's defaults. There are also DataContract classes under CompAnalytics.X9.JPMorganAuthoring that specifically model only the non-static fields needed when sending these files to JPMorgan. While these have been left in for compatibility with our original use case, these specialized classes & methods can be safely ignored and the library can be used for general-purpose X9 file creation.
  3. To reduce complexity, the library only supports one dynamic-length field per record. As a result, the Image View Data Record (Records.ImageViewDatRecord) supports arbitrary-length image data (Field 19), but the other dynamic-length fields in that record are not supported and must be left empty to produce a valid file. This includes Field 17, the digital signature, and Field 15, the image reference key. The corresponding length fields for these two fields (14 and 16, respectively), must also be left at their default value, 0, indicating that the fields both have a length of zero bytes.
  4. Images are provided to the ImageViewDataRecord by supplying a byte[] representing the image file. These must be from TIFF images compressed with CCITT Group 4. Check your institution for image dimension and resolution requirements.

Additionally, the library takes a dependency on Entity Framework due to its reliance on CompAnalytics.Contracts, our base assembly for all DataContracts sent over the wire in the Composable data analytics platform, of which this library is a component. We would like to remove this dependency, but we currently aren't able to. None of the Entity Framework types referenced by CompAnalytics.Contracts are used by CompAnalytics.X9, so as long as you can include the EF dependency and resolve any type load issues, you won't need to worry about runtime errors caused by version mismatches.

Product Compatible and additional computed target framework versions.
.NET Framework net461 is compatible.  net462 was computed.  net463 was computed.  net47 was computed.  net471 was computed.  net472 was computed.  net48 was computed.  net481 was computed. 
Compatible target framework(s)
Additional computed target framework(s)
Learn more about Target Frameworks and .NET Standard.

NuGet packages

This package is not used by any NuGet packages.

GitHub repositories

This package is not used by any popular GitHub repositories.

Version Downloads Last updated
0.2.0 695 1/7/2020
0.1.1 438 12/19/2019
0.1.0 416 12/19/2019

Added support for ICLr return files (and record types 31, 32, 33, and 35).