github.com/moov-io/imagecashletter@v0.10.1/README.md (about) 1 [](https://github.com/moov-io) 2 3 <p align="center"> 4 <a href="https://moov-io.github.io/imagecashletter/">Project Documentation</a> 5 · 6 <a href="https://moov-io.github.io/imagecashletter/api/#overview">API Endpoints</a> 7 · 8 <a href="https://moov.io/blog/education/imagecashletter-api-guide/">API Guide</a> 9 · 10 <a href="https://slack.moov.io/">Community</a> 11 · 12 <a href="https://moov.io/blog/">Blog</a> 13 <br> 14 <br> 15 </p> 16 17 [](https://godoc.org/github.com/moov-io/imagecashletter) 18 [](https://github.com/moov-io/imagecashletter/actions) 19 [](https://codecov.io/gh/moov-io/imagecashletter) 20 [](https://goreportcard.com/report/github.com/moov-io/imagecashletter) 21 [](https://github.com/moov-io/imagecashletter) 22 [](https://raw.githubusercontent.com/moov-io/ach/master/LICENSE) 23 [](https://slack.moov.io/) 24 [](https://hub.docker.com/r/moov/imagecashletter) 25 [](https://github.com/moov-io/imagecashletter) 26 [](https://twitter.com/moov?lang=en) 27 28 # moov-io/imagecashletter 29 30 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. 31 32 ImageCashLetter implements a reader, writer, and validator for X9’s Specifications for [Image Cash Letter](https://en.wikipedia.org/wiki/Check_21_Act) (ICL) to provide Check 21 services in an HTTP server and Go library. The HTTP server is available in a [Docker image](#docker) and the Go package `github.com/moov-io/imagecashletter` is available. 33 34 ## Table of contents 35 36 - [Project status](#project-status) 37 - [Usage](#usage) 38 - As an API 39 - [Docker](#docker) ([Config](#configuration-settings)) 40 - [Google Cloud](#google-cloud-run) ([Config](#configuration-settings)) 41 - [Data persistence](#data-persistence) 42 - [As a Go module](#go-library) 43 - [As an in-browser parser](#in-browser-icl-file-parser) 44 - [Learn about Image Cash Letter](#learn-about-image-cash-letter) 45 - [Getting help](#getting-help) 46 - [Supported and tested platforms](#supported-and-tested-platforms) 47 - [Contributing](#contributing) 48 - [Related projects](#related-projects) 49 50 ## Project status 51 52 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! 53 54 ## Usage 55 The Image Cash Letter project implements an HTTP server and [Go library](https://pkg.go.dev/github.com/moov-io/imagecashletter) for creating and modifying ICL files. We also have some [examples](https://pkg.go.dev/github.com/moov-io/imagecashletter/examples) of the reader and writer. 56 57 ### Docker 58 59 We publish a [public Docker image `moov/imagecashletter`](https://hub.docker.com/r/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](https://quay.io/repository/moov/imagecashletter?tab=tags) published as `quay.io/moov/imagecashletter`. 60 61 Pull & start the Docker image: 62 ``` 63 docker pull moov/imagecashletter:latest 64 docker run -p 8083:8083 -p 9093:9093 moov/imagecashletter:latest 65 ``` 66 67 List files stored in-memory: 68 ``` 69 curl localhost:8083/files 70 ``` 71 ``` 72 null 73 ``` 74 75 Upload an x9 file (binary): 76 ``` 77 curl -X POST --data-binary "@./test/testdata/valid-ascii.x937" http://localhost:8083/files/create 78 ``` 79 ``` 80 {"id":"<YOUR-UNIQUE-FILE-ID>","fileHeader":{"id":"","standardLevel":"03","testIndicator":"T","immediateDestination":"061000146","immediateOrigin":"026073150", ... 81 ``` 82 83 Retrieve an existing x9 file (JSON): 84 ``` 85 curl http://localhost:8083/files/<YOUR-UNIQUE-FILE-ID> 86 ``` 87 ``` 88 {"id":"<YOUR-UNIQUE-FILE-ID>","fileHeader":{"id":"","standardLevel":"03","testIndicator":"T","immediateDestination":"061000146","immediateOrigin":"026073150", ... 89 ``` 90 91 Create an x9 file from JSON: 92 ``` 93 curl -X POST -H "content-type: application/json" localhost:8083/files/create --data @./test/testdata/icl-valid.json 94 ``` 95 ``` 96 {"id":"<YOUR-UNIQUE-FILE-ID>","fileHeader":{"id":"","standardLevel":"35","testIndicator":"T","immediateDestination":"231380104","immediateOrigin":"121042882", ... 97 ``` 98 99 Get the formatted file: 100 ``` 101 curl localhost:8083/files/<YOUR-UNIQUE-FILE-ID>/contents 102 ``` 103 ``` 104 P0135T231380104121042882201810032219NCitadel Wells Fargo US P100123138010412104288220181003201810032219IGA1 Contact Name 5558675552 P200123138010412104288220181003201810039999 1 01 P25 123456789 031300012 555888100001000001 GD1Y030BP261121042882201810031 938383 01 Test Payee Y10 105 ... 106 ``` 107 108 ### Google Cloud Run 109 110 To get started in a hosted environment you can deploy this project to the Google Cloud Platform. 111 112 From your [Google Cloud dashboard](https://console.cloud.google.com/home/dashboard) create a new project and call it: 113 ``` 114 moov-icl-demo 115 ``` 116 117 Enable the [Container Registry](https://cloud.google.com/container-registry) API for your project and associate a [billing account](https://cloud.google.com/billing/docs/how-to/manage-billing-account) if needed. Then, open the Cloud Shell terminal and run the following Docker commands, substituting your unique project ID: 118 119 ``` 120 docker pull moov/imagecashletter 121 docker tag moov/imagecashletter gcr.io/<PROJECT-ID>/imagecashletter 122 docker push gcr.io/<PROJECT-ID>/imagecashletter 123 ``` 124 125 Deploy the container to Cloud Run: 126 ``` 127 gcloud run deploy --image gcr.io/<PROJECT-ID>/imagecashletter --port 8083 128 ``` 129 130 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: 131 132 ``` 133 https://YOUR-ICL-APP-URL.a.run.app 134 ``` 135 136 Now you can list files stored in-memory: 137 ``` 138 curl https://YOUR-ICL-APP-URL.a.run.app/files 139 ``` 140 You should get this response: 141 ``` 142 null 143 ``` 144 145 146 ### Configuration settings 147 148 The following environmental variables can be set to configure behavior in ImageCashLetter. 149 150 | Environmental Variable | Description | Default | 151 |-----|-----|-----| 152 | `READER_BUFFER_SIZE` | Size of buffer to use with `bufio.Scanner`. | Check `bufio.MaxScanTokenSize` | 153 | `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 | 154 | `HTTPS_KEY_FILE` | Filepath of a private key matching the leaf certificate from `HTTPS_CERT_FILE`. | Empty | 155 156 ### Data persistence 157 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. 158 159 ### Go library 160 161 This project uses [Go Modules](https://go.dev/blog/using-go-modules) and Go v1.18 or newer. See [Golang's install instructions](https://golang.org/doc/install) for help setting up Go. You can download the source code and we offer [tagged and released versions](https://github.com/moov-io/imagecashletter/releases/latest) as well. We highly recommend you use a tagged release for production. 162 163 ``` 164 $ git@github.com:moov-io/imagecashletter.git 165 166 # Pull down into the Go Module cache 167 $ go get -u github.com/moov-io/imagecashletter 168 169 $ go doc github.com/moov-io/imagecashletter CashLetter 170 ``` 171 172 The package [`github.com/moov-io/imagecashletter`](https://pkg.go.dev/github.com/moov-io/imagecashletter) offers a Go-based Image Cash Letter file reader and writer. To get started, check out a specific example: 173 174 ICL File | Read | Write | 175 |---------|------|-------| 176 | [Link](examples/imagecashletter-read/iclFile.x937) | [Link](examples/imagecashletter-read/main.go) | [Link](examples/imagecashletter-write/main.go) | 177 178 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())`. 179 180 The following options are currently supported: 181 | Option | Description | 182 |-----|-----| 183 | `ReadVariableLineLengthOption` | Allows Reader to split ICL files based on the Inserted Length Field. | 184 | `ReadEbcdicEncodingOption` | Allows Reader to decode scanned lines from EBCDIC to UTF-8. | 185 | `WriteVariableLineLengthOption` | Instructs the Writer to begin each record with the appropriate Inserted Length Field. | 186 | `WriteEbcdicEncodingOption` | Allows Writer to write file in EBCDIC. | 187 188 189 ### In-browser ICL file parser 190 Using our [in-browser utility](http://oss.moov.io/x9/), 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. 191 192 ## Learn about Image Cash Letter 193 - [Intro to ICL](./docs/intro.md) 194 - [ICL File Structure](./docs/file-structure.md) 195 196 ## Getting help 197 198 channel | info 199 ------- | ------- 200 [Project Documentation](https://moov-io.github.io/imagecashletter/) | Our project documentation available online. 201 Twitter [@moov](https://twitter.com/moov) | You can follow Moov.io's Twitter feed to get updates on our project(s). You can also tweet us questions or just share blogs or stories. 202 [GitHub Issue](github.com/moov-io/imagecashletter/issues) | If you are able to reproduce a problem please open a GitHub Issue under the specific project that caused the error. 203 [moov-io slack](https://slack.moov.io/) | Join our slack channel to have an interactive discussion about the development of the project. 204 205 ## Supported and tested platforms 206 207 - 64-bit Linux (Ubuntu, Debian), macOS, and Windows 208 - Raspberry Pi 209 210 Note: 32-bit platforms have known issues and are not supported. 211 212 ## Contributing 213 214 Yes please! Please review our [Contributing guide](CONTRIBUTING.md) and [Code of Conduct](CODE_OF_CONDUCT.md) to get started! 215 216 This project uses [Go Modules](https://go.dev/blog/using-go-modules) and Go v1.18 or newer. See [Golang's install instructions](https://golang.org/doc/install) for help setting up Go. You can download the source code and we offer [tagged and released versions](https://github.com/moov-io/imagecashletter/releases/latest) as well. We highly recommend you use a tagged release for production. 217 218 ### Releasing 219 220 To make a release of imagecashletter simply open a pull request with `CHANGELOG.md` 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. 221 222 ### Testing 223 224 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](https://app.codecov.io/gh/moov-io/imagecashletter/). 225 226 ### Fuzzing 227 228 We currently run fuzzing over ACH in the form of a [Github Action](https://github.com/moov-io/imagecashletter/actions/workflows/fuzz.yml). Please report crashes examples to [`oss@moov.io`](mailto:oss@moov.io). Thanks! 229 230 ## Related projects 231 As part of Moov's initiative to offer open source fintech infrastructure, we have a large collection of active projects you may find useful: 232 233 - [Moov Watchman](https://github.com/moov-io/watchman) offers search functions over numerous trade sanction lists from the United States and European Union. 234 235 - [Moov Fed](https://github.com/moov-io/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. 236 237 - [Moov Wire](https://github.com/moov-io/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. 238 239 - [Moov ACH](https://github.com/moov-io/ach) provides ACH file generation and parsing, supporting all Standard Entry Codes for the primary method of money movement throughout the United States. 240 241 - [Moov Metro 2](https://github.com/moov-io/metro2) 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. 242 243 ## License 244 245 Apache License 2.0 - See [LICENSE](LICENSE) for details.