Your guide to the Moov ImageCashLetter API
The Moov ImageCashLetter project features an API with several operations for X9 files, including bidirectional conversion between ASCII/EBCDIC and JSON formats. While the project’s primary API documentation contains plenty of technical details and examples, the purpose of this guide is to serve as a launching point for new users. We’ll run through a few basic examples of creating, fetching, deleting, and modifying files.
Background
Image cash letters electronically transport check payments using a standard format. The majority of image cash letters follow the ANSI X9 specifications that deal with the electronic check and image data, X9.37, and its more recent iteration, X9.100-187. If you’d like to dive further into these standards and their applications, check out our additional documentation on X9.
Initial setup
To get started with the ImageCashLetter API, first install Docker and clone the ImageCashLetter project onto your system. From the project’s main directory, build the Docker image with docker build -t moov/imagecashletter . and run it with docker run -p 8083:8083 -p 9093:9093 moov/imagecashletter. This step runs the API service on port 8083 with admin metrics on 9093.
To ensure the service is active, you can ping it with curl localhost:8083/ping. If it’s up and running, you’ll receive an HTTP 200 status with PONG as the response body. Otherwise, you’ll see something like Failed to connect to localhost port 8083: Connection refused.
EBCDIC configuration
ImageCashLetter handles ASCII files by default. To work with EBCDIC-encoded files instead, you’ll need to manually pass read and write options in cmd/server/files.go, adding imagecashletter.ReadEbcdicEncodingOption() to line 115 and imagecashletter.WriteEbcdicEncodingOption() to line 265. Remember to rebuild the Docker image after making these changes.
Listing files
curl localhost:8083/files will access a list of image cash letters stored in memory. Opening a browser window and setting the URL to localhost:8083/files lets you view the file list quickly. Assuming you haven’t uploaded any files yet, it will return null.
Each file is stored in JSON format and assigned a unique file ID if not already provided within its contents. Since these files can be pretty significant, I recommend using an in-browser JSON formatting tool or jq to view them.
Creating files
With the /create endpoint, you can create image cash letter files on the server. You can choose to upload ASCII, EBCDIC, or JSON representations using this same endpoint. We have many sample files in the test/testdata directory of our project and refer to these examples throughout this article.
Uploading an ASCII/EBCDIC representation can be done with:
curl -X POST --data-binary "@valid-ascii.x937" localhost:8083/files/create
Similarly, you can upload a JSON image cash letter with:
curl -X POST -H "content-type: application/json" -d "@valid-x937.json" localhost:8083/files/create
If creation is successful in either case, you’ll receive a response with the file’s JSON representation. If not, you’ll get a parsing error, as validation is performed automatically upon submission.
Fetching files
Once a file is on the server, you can fetch its contents by supplying its file ID. Use the cURL -o flag to save the files locally.
To retrieve the JSON representation, use:
curl localhost:8083/files/<YOUR-UNIQUE-FILE-ID>
To retrieve ASCII/EBCDIC contents, use:
curl localhost:8083/files/<YOUR-UNIQUE-FILE-ID>/contents
Deleting files
Deleting files stored in memory is as simple as sending a curl DELETE request. For example:
curl -X DELETE localhost:8083/files/<YOUR-UNIQUE-FILE-ID>
Updating file headers
The ImageCashLetter API allows you to update the file header of a created file by supplying its ID and some new data. You don’t have to provide an entire header—just the fields you want to update.
To update the immediateDestinationName, for example, first create a JSON file with the following contents: {"immediateDestinationName": "Pineapples Inc."}. Then specify a file’s ID and update its header:
curl -X POST -d "@newHeader.json" localhost:8083/files/<YOUR-UNIQUE-FILE-ID>
Add or remove CashLetters
You can also add or remove CashLetters from an existing file.
To add one, use:
curl -X POST -d "@newCashLetter.json" localhost:8083/files/<YOUR-UNIQUE-FILE-ID>/cashLetters
This step appends the new CashLetter to the end of the file.
To delete one, use:
curl -X DELETE localhost:8083/files/<YOUR-UNIQUE-FILE-ID>/cashLetters/<YOUR-UNIQUE-CASHLETTER-ID>
This step deletes the CashLetter from the file.
Setting a unique ID when adding CashLetters is not currently supported, which means they cannot be deleted. However, you can assign IDs in the initial CashLetter file creation process.
Validating files
Although validation occurs during the file creation process, we still offer a /validate endpoint, which helps validate changes to existing files. To validate a file, simply use:
curl localhost:8083/files/<YOUR-UNIQUE-FILE-ID>/validate
For example, if you deleted all CashLetters on a file, the file would be invalid. Validation would report {"error":"file=fileID was invalid: CashLetters must have []*CashLetters to be built"}.
Summary
We hope this walkthrough helps you get started with ImageCashLetter and serves as a quick refresher for current users. The API is only a fraction of the entire project, so we encourage you to visit ImageCashLetter on GitHub too! If you have any questions or suggestions for ImageCashLetter, please contact the Moov team on Slack (#imagecashletter channel) or submit an issue.
