ACH Syntax Highlighter and Validator

A professional Visual Studio Code extension for developers and treasury professionals working with NACHA ACH files. It provides deep validation, intelligent syntax highlighting, and context-aware tooltips for standard and international transactions.

Validation Scope

The extension validates deterministic ACH file-format rules that can be established from the file bytes: fixed-width layouts, record order, field syntax, SEC/transaction compatibility, trace relationships, addenda structure, routing checksums, and calculated controls. JSON and SARIF reports identify this result as formatValid and always set complianceCertified to false.

A structurally valid file is not, by itself, proof of Nacha Rules compliance. Authorization evidence, processing and return time limits, routing-directory eligibility, sanctions screening, participant agreements, fraud-monitoring procedures, purpose-specific Company Entry Descriptions, trading-partner addenda schemas, annual audits, and risk assessments require evidence outside the file. See RULESET.md and the versioned machine-readable ruleset in rules/.

Features

🔍 Deep Validation

• Bank Routing Checksums: Automatically validates RDFI routing-number check digits using the standard routing checksum algorithm.
• Aggregate Totals: Verifies Batch Controls (Type 8) and File Controls (Type 9) against actual entry counts, debit/credit sums, and entry hashes.
• Record Integrity: Checks for correct record lengths (94 characters), mandatory fields, and proper record ordering (Header -> Batch -> Entry -> Control).
• Rule-Based Diagnostics: Reports stable rule codes, expected and actual values, and related header/control locations across physical, structural, field, relational, and SEC-specific validation.
• Validation Profiles: Supports strict blocking, institution-compatible unblocked files, and an opt-in net-zero balanced-file profile.

🧩 SEC-Aware Entry Details

• Contextual Field Names: Decodes ARC/BOC/RCK check serials, POP check/terminal fields, CCD/CTX corporate Receiver fields, and WEB/TEL Payment Type Codes using their actual SEC meaning.
• Required Data Rules: Validates DFI account numbers, required Receiver names, converted-check serial numbers, and POP terminal city/state fields for common domestic Entry Detail layouts.
• WEB Credit Rules: Requires the consumer Originator name carried in a Person-to-Person WEB credit.
• Readable Payment Types: Requires and decodes the recognized R, S, and ST WEB Payment Type values.
• Sensitive Check Data: Masks converted-check serial numbers by default in decoded views.

🧮 Automated Accounting Advice (ADV)

• Distinct Fixed-Width Layouts: Decodes the ADV Entry Detail, Batch Control, and File Control formats instead of applying standard payment fields.
• Accounting Arithmetic: Uses the 12-digit ADV entry amount and 20-digit batch/file debit and credit totals throughout validation, summaries, navigation, and safe fixes.
• ADV Semantics: Enforces service class 280, transaction codes 81–88, routing fields, required account/name data, Julian dates, and four-digit within-batch sequences.
• Safe Sequence Repair: Renumbers only the ADV sequence field without overwriting the ACH Operator routing number or advice date.
• File Boundary: Rejects mixing ADV and non-ADV batches because their File Control amount layouts differ.

📬 ACK/ATX Acknowledgments

• Correct Entry Layouts: Decodes the Original Entry Trace Number and the distinct ACK company-name and ATX company/count fields.
• Acknowledgment Rules: Enforces transaction codes 24/34, zero amounts, required account/company data, and numeric original traces.
• Optional Addenda: Allows one type-05 acknowledgment addenda and validates its indicator, sequence, and Entry Detail trace link.
• ATX Counts: Checks the four-digit declared addenda count and reserved columns in the corporate acknowledgment layout.

🏛️ CIE/DNE/ENR Specialized Entries

• Contextual Layouts: Decodes CIE's reversed name/reference fields and ENR's count, agency, reserved, and discretionary fields correctly.
• Required Identity Data: Validates the account, individual, customer-reference, and receiving-agency fields required by each format.
• Non-Monetary Notices: Enforces forward codes 23/33 (plus valid return codes for DNE), zero amounts, and mandatory type-05 addenda for DNE and ENR entries.
• Addenda Controls: Enforces CIE/DNE single-addenda limits, ENR's 9,999-record maximum, nonblank DNE/ENR convention data, and safe ENR count repair.

🏧 MTE/POS/SHR Terminal Entries

• Terminal Layouts: Decodes each Entry Detail format and the two variants of type-02 terminal addenda with their exact field boundaries.
• Terminal Validation: Checks required terminal identifiers, serials, locations, cities, states, transaction dates, and MTE transaction times.
• Card Semantics: Decodes and validates POS/SHR card transaction types plus SHR expiration, document-reference, card-account, and debit-only requirements.
• Prenote Awareness: Requires one type-02 addenda for live terminal entries while allowing MTE/POS/SHR prenotes without addenda.
• Complete Trace Handling: Navigates and safely synchronizes the full 15-digit terminal addenda trace during fixes and explicit renumbering.

✂️ TRX Truncated Entries Exchange

• Corporate Layout: Decodes the four-digit addenda count, Receiving Company Name/ID, reserved columns, and Item Type Indicator.
• TRX Rules: Enforces debit entries, required account/Receiver data, and up to 9,999 type-05 addenda records.
• Prenote Exception: Requires addenda for live TRX entries while permitting prenotes without addenda.
• Safe Count Repair: Reconciles declared and attached addenda counts without changing optional check-safekeeping payloads.
• Sequence Integrity: Reuses type-05 sequence and Entry Detail linkage validation across large TRX addenda sets.

🧾 TRC/XCK Check Entries

• Explicit SEC Support: Recognizes TRC and XCK instead of treating them as unknown SEC codes.
• Check Data Rules: Applies debit-only compatibility, required account/check-serial data, and SEC-specific addenda limits.
• Contextual Reading: Labels and decodes the check serial and Receiver fields using the TRC/XCK layouts.

🌐 IAT Format Support

• International Transactions: Deterministic fixed-width and relationship validation for International ACH Transactions (IAT).
• Contextual Parsing: Switches field definitions automatically when an IAT batch is detected.
• Complete Addenda Layouts: Decodes the authoritative fixed-width fields for mandatory types 10–16, optional remittance type 17, and foreign-correspondent-bank type 18.
• Mandatory Addenda: Validates the presence and order of the seven required IAT addenda records, their required fields, reserved columns, and Entry Detail sequence links.
• Optional Addenda Rules: Validates type 17/18 ordering, individual and combined maxima, independent sequence numbers, bank-identification qualifiers, and branch-country formatting.

↩️ Returns and Notifications of Change

• Dedicated Addenda Layouts: Decodes type 99 Return and type 98 Notification of Change records with their actual fixed-width fields instead of treating them as payment addenda.
• Return Validation: Uses an effective-dated Return Reason Code table and validates original trace and RDFI identifiers, conditional Date of Death, and the complete related trace number.
• NOC Validation: Recognizes COR batches and validates transaction codes, zero-dollar amounts, corrected data, reserved fields, and required type 98 addenda.
• IAT Variants: Uses the IAT-specific Return payment-amount and NOC corrected-data widths.
• Safe Trace Repair: Highlights and synchronizes the complete 15-digit Return/NOC addenda trace when it differs from the related Entry Detail record.

🔄 Reversal Awareness

• Explicit Classification: Recognizes batches whose Company Entry Description is the required uppercase REVERSAL value and labels them in the decoded explorer.
• Focused Validation: Flags incorrectly cased reversal descriptions and non-payment transaction kinds inside reversal batches.
• Safe Description Fix: Corrects only unambiguous case/spacing mistakes in the fixed-width description field.
• Visible Counts: Includes reversal batch and entry counts in file summaries and redacted JSON reports.
• No False Comparison Claims: Does not claim to verify Company ID, SEC, amount, originator, timing, or direction against an original entry that is not present.

🧪 Prenotification Awareness

• SEC-Aware Classification: Identifies prenotes from their transaction code without mislabeling DNE or ENR non-dollar entries that share codes.
• Zero-Amount Validation: Reports a dedicated diagnostic when a prenote carries a nonzero amount.
• Valid Mixed Batches: Supports prenotes mixed with live entries and permits addenda according to the batch SEC rules.
• IAT Requirements Preserved: IAT prenotes still require the seven mandatory IAT addenda records.
• Visible Counts: Shows prenote entries in the decoded explorer, file summary, and redacted JSON report.
• Timing Boundary: Does not claim to verify the three-Banking-Day waiting period from a single file.

0️⃣ Zero-Dollar Entry Awareness

• Contextual Classification: Identifies zero-dollar CCD, CTX, and IAT entries without mislabeling ACK/ATX acknowledgment entries that reuse transaction codes 24 and 34.
• Required Remittance Data: Requires at least one addenda record for zero-dollar CCD and CTX entries while preserving the seven mandatory IAT addenda rules.
• Zero-Amount Validation: Reports a dedicated diagnostic when a zero-dollar entry carries a nonzero amount.
• ACK/ATX Compatibility: Restricts acknowledgment batches to transaction codes 24 or 34 and displays acknowledgment-specific descriptions.
• Visible Counts: Shows zero-dollar entries in the decoded explorer, file summary, and redacted JSON report.

⚖️ Net Position and Balanced-File Profiles

• Exact Net Position: Classifies each file as net zero, net credit, or net debit using exact bigint cents.
• Default Flexibility: Standard validation accepts both balanced and unbalanced origination workflows.
• Opt-In Enforcement: The built-in balanced profile, or requireNetZero in a custom profile, requires calculated debits and credits to net to zero.
• Visible Funding Context: Displays the signed net amount in summaries, the decoded explorer, and redacted JSON reports.
• Honest Offset Boundary: Net-zero arithmetic is not presented as proof that a specific entry is an offset; identifying the settlement account remains institution-specific.

✅ Micro-Entry Awareness

• ACCTVERIFY Classification: Recognizes and labels batches using the mandatory uppercase ACCTVERIFY Company Entry Description.
• Credit Amount Rules: Requires credit Micro-Entries to be between 1 and 99 cents and use live payment transaction codes.
• Offset Review: Groups entries by originator and receiver account, warning when debits found in the file exceed credits or potentially corresponding entries use different Effective Entry Dates.
• Safe Description Fix: Corrects unambiguous ACCTVERIFY casing mistakes without changing payment instructions.
• Visible Counts: Shows Micro-Entry batches and entries in summaries, the decoded explorer, and redacted JSON reports.
• External Controls: Does not claim to verify recognizable Company Names, separately submitted corresponding files, completion of account verification, or required fraud monitoring.

🎨 Visual Intelligence

• Alternating Field Highlighting: Provides visual cues for field boundaries with alternating colors to make fixed-width files readable.
• Interactive Hovers: Hover over any position to see the field name, description, start/end positions, and the raw value.
• Batch Separation: Visual borders and unique alternating backgrounds per batch for easy navigation.

🧭 Decoded ACH Explorer

• Expandable Hierarchy: Browse files as batches, entries, addenda, records, and fields from the Explorer sidebar.
• Raw and Decoded Values: See fixed-width values beside formatted amounts, dates, transaction codes, service classes, and SEC descriptions.
• Synchronized Navigation: Selecting a decoded field reveals its exact raw characters, while moving the editor cursor selects the matching explorer field.
• Privacy by Default: Account, company/originator, and individual identifiers are masked unless explicitly enabled in settings.
• Validation Context: File, batch, entry, record, and field nodes show error/warning badges and aggregate totals.

🧱 Navigation and Reading Aids

• Outline and Breadcrumbs: Navigate file, batch, entry, and addenda symbols using VS Code Outline, breadcrumbs, and sticky scroll.
• Structural Folding: Collapse batches, entry/addenda groups, and file padding.
• Matching Records: Jump between file headers/controls, batch headers/controls, and entry/addenda records.
• Problem Traversal: Move directly to the next or previous ACH validation problem.
• Fixed-Width Context: See the current column and field in the status bar, with an optional column-94 guide and field-name inlay hints.
• Related Fields: Header/control values, aggregate totals, and entry/addenda trace relationships highlight together.

🛠 Safe Quick Fixes

• Inline Quick Fixes: Correct routing check digits, derived control values, header/control synchronization, and addenda metadata directly from Problems or the lightbulb menu.
• Derived Recalculation: Rebuild batch and file counts, hashes, debit/credit totals, and block counts from actual entries.
• Safe Fix All: Apply only deterministic fixed-format repairs, including padding and unambiguous trailing spaces.
• Explicit Renumbering: Renumber batches, traces, and addenda sequences only through a separately invoked command.
• Diff Before Apply: Every multi-record command opens a comparison and waits for confirmation.
• Ambiguity Guardrails: The extension never guesses routing numbers, dates, transaction/SEC codes, account data, or truncation.

📋 Profiles, Reports, and Automation

• Named Profiles: Define institution/operator profiles that extend strict or unblocked validation behavior.
• Explained Overrides: Change or suppress exact rules, categories, or all rules only with a recorded reason.
• Versioned Rules: Reports identify ruleset version 2026.06.22.1 independently from the extension version.
• Redacted Reports: Export JSON or SARIF without exposing account numbers and individual identifiers.
• Headless CLI: Run the same parser and validator in CI, scripts, and pre-upload workflows.
• Text Detection: High-confidence ACH content in .txt files can switch to ACH language mode with one click.

⚙️ Highly Customizable

• Color Picker Support: Choose your own colors for every record type (1-9) directly in the VS Code Settings UI.
• Theme Friendly: Supports standardized 8-character hex colors (#rrggbbaa) for transparency.

♿ Accessible and Large-File Friendly

• Non-Color Labels: Textual record labels appear after column 94, so record meaning never depends on color alone.
• High-Contrast Boundaries: High-contrast themes automatically add dotted field boundaries; the option is also independently configurable.
• Debounced Analysis: Active edits wait briefly before triggering full validation.
• Viewport Rendering: Field decorations and record labels are limited to the visible editor region plus a buffer.
• Bounded UI Trees: The explorer limits materialized Entry nodes while totals and validation continue to cover the complete file.
• Bounded Problems: VS Code Problems can be capped while JSON, SARIF, and CLI results remain complete.
• Performance Regression: The automated suite parses, validates, and summarizes a 10,000-entry ACH file.

Usage

Simply open any file with the .ach extension. The extension activates automatically and provides:

1. Syntax Highlighting: Different backgrounds for File Header, Batch Header, Entry Details, etc.
2. Diagnostics: Errors and warnings in the "Problems" panel for missing totals, invalid routing, or record length issues.
3. Hover Info: Detailed NACHA file specification data directly in your editor.
4. Decoded ACH Explorer: Expand the file hierarchy in the Explorer sidebar and select any field to reveal its raw source range.
5. ACH Navigation Commands: Use the Command Palette or editor context menu to jump to matching records and validation problems.
6. Safe Repairs: Use individual Quick Fixes or preview Recalculate All Derived Fields, Apply All Safe Fixes, and sequence-renumbering commands.
7. Reports and CI: Export redacted reports from VS Code or run ach-validate from the command line.

Headless Validation

ach-validate payments.ach
ach-validate --format sarif payments.ach > ach-results.sarif
ach-validate --fail-on warning payments.ach
ach-validate --profile balanced payments.ach
ach-validate --rule 'ACH-PHYSICAL-PADDING-COUNT=off:Processor accepts unblocked files' payments.ach

The CLI exits 1 when the configured threshold is reached, 2 for usage/read/profile failures, and 0 otherwise. A zero exit code means the configured deterministic file-format checks passed; it is not a compliance certification.

Named Profile Example

{
  "nachaFileParser.validationProfile": "partner-bank",
  "nachaFileParser.validationProfiles": {
    "partner-bank": {
      "extends": "unblocked",
      "displayName": "Partner Bank",
      "ruleOverrides": {
        "ACH-SEC-TRANSACTION-CODE": {
          "severity": "warning",
          "reason": "Partner performs this compatibility check after upload"
        }
      }
    }
  }
}

Extension Settings

This extension contributes the following settings:

• nachaFileParser.validationProfile: Select the built-in nacha, unblocked, or balanced profile or a custom named profile.
• nachaFileParser.validationProfiles: Define named institution/operator profiles, including optional requireNetZero arithmetic enforcement.
• nachaFileParser.ruleOverrides: Override exact rules, categories, or all rules with a severity and explanation.
• nachaFileParser.rowColoring: Color complete batches or individual record types.
• nachaFileParser.recordTypeColors: Customize background colors for each record type (1-9).
• nachaFileParser.batchRowColors: Colors for alternating batches.
• nachaFileParser.fieldColors: Text colors for alternating fields.
• nachaFileParser.paddingRowColor: Color for blocking/filler records.
• nachaFileParser.showRecordTypeLabels: Show textual record labels after column 94 (enabled by default).
• nachaFileParser.accessibleFieldBoundaries: Add non-color field boundaries (automatic in high-contrast themes).
• nachaFileParser.maskSensitiveValues: Mask account numbers and individual identifiers in the Decoded ACH explorer (enabled by default).
• nachaFileParser.showColumnRuler: Show the fixed-width boundary at column 94 (enabled by default).
• nachaFileParser.showFieldInlayHints: Show field names directly at fixed-width boundaries (disabled by default).
• nachaFileParser.detectAchInTextFiles: Offer ACH language mode for high-confidence .txt files (enabled by default).
• nachaFileParser.validationDebounceMs: Configure the edit-to-validation delay.
• nachaFileParser.explorerEntryLimit: Limit Entry nodes rendered in the Decoded ACH explorer.
• nachaFileParser.maxDiagnostics: Limit Problems entries without limiting reports or CLI results.

Installation

Install via the VS Code Marketplace or by downloading the .vsix file from the repository.

Developed by Ravi Ranjan.