Imagecashletter
X9’s Specifications for ICL (Image Cash Letter) to provide Check 21 services. The HTTP server is available in a Docker image and the Go package is available.
Install / Use
/learn @moov-io/ImagecashletterREADME
moov-io/imagecashletter
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 github.com/moov-io/imagecashletter is available.
Table of contents
- Project status
- Usage
- Learn about Image Cash Letter
- Getting help
- Supported and tested platforms
- Contributing
- Related projects
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!
Usage
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.
Docker
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 quay.io/moov/imagecashletter.
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
null
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:
moov-icl-demo
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 gcr.io/<PROJECT-ID>/imagecashletter
docker push gcr.io/<PROJECT-ID>/imagecashletter
Deploy the container to Cloud Run:
gcloud run deploy --image gcr.io/<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:
https://YOUR-ICL-APP-URL.a.run.app
Now you can list files stored in-memory:
curl https://YOUR-ICL-APP-URL.a.run.app/files
You should get this response:
null
Configuration settings
The following environmental variables can be set to configure behavior in ImageCashLetter.
| Environmental Variable | Description | Default |
|-----|-----|-----|
| READER_BUFFER_SIZE | Size of buffer to use with bufio.Scanner. | Check bufio.MaxScanTokenSize |
| 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 |
| FRB_COMPATIBILITY_MODE | If set, enables Federal Reserve Bank (FRB) compatibility mode. | 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 Go v1.18 or newer. 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.
$ git@github.com:moov-io/imagecashletter.git
# Pull down into the Go Module cache
$ go get -u github.com/moov-io/imagecashletter
$ go doc github.com/moov-io/imagecashletter CashLetter
The package github.com/moov-io/imagecashletter 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 ope
