fedach

README

fedach

Go library and CLI for parsing output files from the Federal Reserve's FedPayments Reporter service.

FedPayments Reporter produces operational and exception reports for ACH files in several formats, including fixed-width visual text reports (often delivered with newlines removed or flattened), Excel (.xlsx), and PDF. This module makes those reports machine-readable and programmatically usable.

Features

• Robust stage-1 extractor for noisy, concatenated, or fixed-width tagged report formats (no reliance on \n separators)
• Two-stage architecture: reliable logical record extraction first, semantic/structured parsing later
• Small, extensible CLI that dispatches by file extension
• Currently ships with first-class support for FAHK / ACK ("Acknowledgement of ACH File Deposits") reports via pkg/ack

Installation

CLI

# Install the latest released version
go install github.com/moov-io/fedach/cmd/fedach@latest

# Or build from source
git clone https://github.com/moov-io/fedach.git
cd fedach
make build
./bin/fedach --help

Library

go get github.com/moov-io/fedach/pkg/ack

Quick Start

CLI

The CLI inspects the file extension and routes to the appropriate handler.

# Shorthand (most convenient)
./fedach testdata/ack/raw/ACHFAHK673960043AIN202605261654134.ack

# Explicit subcommand
./fedach parse some-report.ack
./fedach parse --help

Output includes:

• Reconstructed visual lines (what a human would have seen on screen)
• The underlying tagged logical records (A–Z + Z terminators)
• Summary of any file-level (I/J/K/Z) or batch-level (W/X/Y/Z) error blocks

Go Library (ACK reports)

import (
    "fmt"
    "os"

    "github.com/moov-io/fedach/pkg/ack"
)

data, _ := os.ReadFile("report.ack")

// Stage 1: extract logical records (the foundation for everything else)
recs := ack.Split(data)
lines := ack.SplitLines(data)

// recs is []ack.Record — each entry preserves the original bytes for that
// logical record (including its single-letter prefix).
for _, r := range recs {
    fmt.Printf("[%c] %s\n", r.Prefix, string(r.Content))
}

// Helper to group the two common error block patterns
fileErrs, batchErrs := ack.FindErrorBlocks(recs)

See the full pkg/ack documentation for format quirks, golden testing strategy, and the Record type.

Architecture

This project follows a deliberate two-stage model:

1. Stage 1 (Extraction) — Split / SplitLines and friends reliably turn messy physical input (concatenated lines, embedded newlines, repeated page headers, glued tags, etc.) into a clean sequence of logical records or reconstructed visual lines. The exact original content of each record is preserved.
2. Stage 2 (Semantic Parsing) — Future packages under pkg/ will consume the stage-1 output and turn it into typed Go structs (file headers, batch totals, error details, quoted original ACH entry data, etc.).

This separation keeps the hard low-level parsing work reusable and testable independently of any particular report's business meaning.

New report types should follow the same pattern:

• Live under pkg/<something>/
• Provide their own Split* style extractors when needed
• The root CLI will grow a handler for the corresponding file extension

Currently Supported

Report	Extension	Package	Status
FAHK / ACK (Acknowledgement of ACH File Deposits)	.ack	pkg/ack	Stage 1 complete + CLI
Other FedPayments Reporter formats (various Excel, PDF, fixed-width)	(various)	—	Planned

See testdata/ for real (anonymized) sample files from the Federal Reserve.

Development

# Run tests (includes golden regression tests for the ACK extractor)
go test ./...

# Build the CLI with a dev version stamp
make build

# Full project checks (linting, coverage, etc.)
make check

The ACK package uses a "just a filename" golden table test pattern. Raw inputs live in testdata/ack/raw/ and the corresponding expected line-by-line output lives in testdata/ack/lines/ under the exact same basename. Adding a new regression case is as simple as dropping the pair of files and adding the name to the test slice.

License

Apache License 2.0 — see LICENSE.

Acknowledgements

This project is part of the moov-io family of financial infrastructure libraries. Special thanks to the Federal Reserve Banks for publishing the FedPayments Reporter service and its sample reports.

Documentation

Overview

Package fedach provides Go parsers, utilities, and a CLI for working with the various report files produced by the Federal Reserve Banks' FedPayments Reporter service.

FedPayments Reporter (https://www.frbservices.org/financial-services/ach/fedpayments-reporter/) generates operational and exception reports for ACH files processed by the Federal Reserve. These reports are delivered in several formats, including fixed-width visual text reports (often with newlines removed or flattened), Excel (.xlsx), and PDF.

This module focuses on making those reports machine-readable and programmatically usable. The design follows a two-stage model:

1. Reliable extraction of logical records / visual lines from noisy, concatenated, or fixed-width input (the "stage 1" parser).
2. Semantic parsing of those records into structured Go types for specific report kinds (the "stage 2" parsers, added over time).

Currently Supported Reports

• FAHK / ACK files ("Acknowledgement of ACH File Deposits") via the github.com/moov-io/fedach/pkg/ack subpackage. These use an in-band tagged format with single-letter prefixes (A–Z) and explicit 'Z' terminators. The ack package provides Split, SplitLines, Record, and FindErrorBlocks helpers plus robust reconstruction of the original visual report layout.

Command-Line Tool

A small, extensible CLI lives in cmd/fedach. It dispatches on file extension so it can grow to support additional report types:

go run ./cmd/fedach parse path/to/report.ack
./fedach somefile.ack

The CLI currently understands .ack files and will be extended for other FedPayments Reporter outputs.

Adding New Report Types

New report formats should live under pkg/ (e.g. pkg/returns, pkg/originated) following the same two-stage extraction + semantic model. The root CLI will route based on file extension.

For sample input files see the testdata/ directory, which contains real (anonymized) reports from the Federal Reserve.

Index

• Variables

Variables

var Version string