Skip to content
Switch branches/tags

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

Moov Banner Logo

Project Documentation · API Endpoints · API Guide · Community · Blog

GoDoc Build Status Coverage Status Go Report Card Repo Size Apache 2 License Slack Channel Docker Pulls GitHub Stars Twitter


Moov's mission is to give developers an easy way to create and integrate bank processing into their own software products. Our open source projects are each focused on solving a single responsibility in financial services and designed around performance, scalability, and ease of use.

ImageCashLetter implements a reader, writer, and validator for X9’s Specifications for Image Cash Letter (ICL) to provide Check 21 services in an HTTP server and Go library. The HTTP server is available in a Docker image and the Go package is available.

Table of contents

Project status

Moov ImageCashLetter is actively used in multiple production environments. Please star the project if you are interested in its progress. If you have layers above ImageCashLetter to simplify tasks, perform business operations, or found bugs we would appreciate an issue or pull request. Thanks!


The Image Cash Letter project implements an HTTP server and Go library for creating and modifying ICL files. We also have some examples of the reader and writer.


We publish a public Docker image moov/imagecashletter from Docker Hub or use this repository. No configuration is required to serve on :8083 and metrics at :9093/metrics in Prometheus format. We also have Docker images for OpenShift published as

Pull & start the Docker image:

docker pull moov/imagecashletter:latest
docker run -p 8083:8083 -p 9093:9093 moov/imagecashletter:latest

List files stored in-memory:

curl localhost:8083/files

Upload an x9 file (binary):

curl -X POST --data-binary "@./test/testdata/valid-ascii.x937" http://localhost:8083/files/create
{"id":"<YOUR-UNIQUE-FILE-ID>","fileHeader":{"id":"","standardLevel":"03","testIndicator":"T","immediateDestination":"061000146","immediateOrigin":"026073150", ...

Retrieve an existing x9 file (JSON):

curl http://localhost:8083/files/<YOUR-UNIQUE-FILE-ID>
{"id":"<YOUR-UNIQUE-FILE-ID>","fileHeader":{"id":"","standardLevel":"03","testIndicator":"T","immediateDestination":"061000146","immediateOrigin":"026073150", ...

Create an x9 file from JSON:

curl -X POST -H "content-type: application/json" localhost:8083/files/create --data @./test/testdata/icl-valid.json
{"id":"<YOUR-UNIQUE-FILE-ID>","fileHeader":{"id":"","standardLevel":"35","testIndicator":"T","immediateDestination":"231380104","immediateOrigin":"121042882", ...

Get the formatted file:

curl localhost:8083/files/<YOUR-UNIQUE-FILE-ID>/contents
P0135T231380104121042882201810032219NCitadel      Wells Fargo    US   P100123138010412104288220181003201810032219IGA1   Contact Name 5558675552  P200123138010412104288220181003201810039999   1  01             P25   123456789 031300012       555888100001000001       GD1Y030BP261121042882201810031       938383      01  Test Payee   Y10

Google Cloud Run

To get started in a hosted environment you can deploy this project to the Google Cloud Platform.

From your Google Cloud dashboard create a new project and call it:


Enable the Container Registry API for your project and associate a billing account if needed. Then, open the Cloud Shell terminal and run the following Docker commands, substituting your unique project ID:

docker pull moov/imagecashletter
docker tag moov/imagecashletter<PROJECT-ID>/imagecashletter
docker push<PROJECT-ID>/imagecashletter

Deploy the container to Cloud Run:

gcloud run deploy --image<PROJECT-ID>/imagecashletter --port 8083

Select your target platform to 1, service name to imagecashletter, and region to the one closest to you (enable Google API service if a prompt appears). Upon a successful build you will be given a URL where the API has been deployed:

Now you can list files stored in-memory:


You should get this response:


Configuration settings

The following environmental variables can be set to configure behavior in ImageCashLetter.

Environmental Variable Description Default
HTTPS_CERT_FILE Filepath containing a certificate (or intermediate chain) to be served by the HTTP server. Requires all traffic be over secure HTTP. Empty
HTTPS_KEY_FILE Filepath of a private key matching the leaf certificate from HTTPS_CERT_FILE. Empty

Data persistence

By design, ImageCashLetter does not persist (save) any data about the files or entry details created. The only storage occurs in memory of the process and upon restart ImageCashLetter will have no files or data saved. Also, no in-memory encryption of the data is performed.

Go library

This project uses Go Modules and uses Go v1.14 or higher. See Golang's install instructions for help setting up Go. You can download the source code and we offer tagged and released versions as well. We highly recommend you use a tagged release for production.


# Pull down into the Go Module cache
$ go get -u

$ go doc CashLetter

The package offers a Go-based Image Cash Letter file reader and writer. To get started, check out a specific example:

ICL File Read Write
Link Link Link

ImageCashLetter's file handling behaviors can be modified to accommodate your specific use case. This is done by passing options into ICL's reader and writer during instantiation. For example, to read EBCDID encoded files you would instantiate a reader with NewReader(fd, ReadVariableLineLengthOption(), ReadEbcdicEncodingOption()).

The following options are currently supported:

Option Description
ReadVariableLineLengthOption Allows Reader to split ICL files based on the Inserted Length Field.
ReadEbcdicEncodingOption Allows Reader to decode scanned lines from EBCDIC to UTF-8.
WriteVariableLineLengthOption Instructs the Writer to begin each record with the appropriate Inserted Length Field.
WriteEbcdicEncodingOption Allows Writer to write file in EBCDIC.

In-browser ICL file parser

Using our in-browser utility, you can instantly convert X9 files into JSON. Either paste in ICL file content directly or choose a file from your local machine. This tool is particularly useful if you're handling sensitive PII or want to perform some quick tests, as operations are fully client-side with nothing stored in memory. We plan to support bidirectional conversion in the near future.

Learn about Image Cash Letter

Getting help

channel info
Project Documentation Our project documentation available online.
Twitter @moov You can follow's Twitter feed to get updates on our project(s). You can also tweet us questions or just share blogs or stories.
GitHub Issue If you are able to reproduce a problem please open a GitHub Issue under the specific project that caused the error.
moov-io slack Join our slack channel to have an interactive discussion about the development of the project.

Supported and tested platforms

  • 64-bit Linux (Ubuntu, Debian), macOS, and Windows
  • Raspberry Pi

Note: 32-bit platforms have known issues and are not supported.


Yes please! Please review our Contributing guide and Code of Conduct to get started!

This project uses Go Modules and uses Go v1.14 or higher. See Golang's install instructions for help setting up Go. You can download the source code and we offer tagged and released versions as well. We highly recommend you use a tagged release for production.


To make a release of imagecashletter simply open a pull request with and version.go updated with the next version number and details. You'll also need to push the tag (i.e. git push origin v1.0.0) to origin in order for CI to make the release.


We maintain a comprehensive suite of unit tests and recommend table-driven testing when a particular function warrants several very similar test cases. To run all test files in the current directory, use go test. Current overall coverage can be found on Codecov.


We currently run fuzzing over ImageCashLetter in the form of a moov/imagecashletterfuzz Docker image. You can read more or run the image and report crasher examples to Thanks!

Related projects

As part of Moov's initiative to offer open source fintech infrastructure, we have a large collection of active projects you may find useful:

  • Moov Watchman offers search functions over numerous trade sanction lists from the United States and European Union.

  • Moov Fed implements utility services for searching the United States Federal Reserve System such as ABA routing numbers, financial institution name lookup, and FedACH and Fedwire routing information.

  • Moov Wire implements an interface to write files for the Fedwire Funds Service, a real-time gross settlement funds transfer system operated by the United States Federal Reserve Banks.

  • Moov ACH provides ACH file generation and parsing, supporting all Standard Entry Codes for the primary method of money movement throughout the United States.

  • Moov Metro 2 provides a way to easily read, create, and validate Metro 2 format, which is used for consumer credit history reporting by the United States credit bureaus.


Apache License 2.0 - See LICENSE for details.