API Documentation

Comprehensive guide to using the NACHA File Generator API

Contents

Introduction

The NACHA File Generator API provides a simple way to generate compliant NACHA formatted files for ACH (Automated Clearing House) transactions. These files are used by financial institutions to process electronic fund transfers.

This API handles all the complexities of NACHA file formatting, including fixed-width field formatting, batch and file header/footer generation, control total calculations, hash sum calculations, and record count tracking.

Note: NACHA files must adhere to strict formatting rules to be accepted by financial institutions. This API ensures your files meet these requirements.

API Endpoints

The API provides two main endpoints for generating and validating NACHA files.

POST /api/v1/nacha/generate

Generates a compliant NACHA formatted file from the provided data.

Request

  • Content-Type: application/json
  • Body: JSON object containing file header and batches (see Request Format section)

Response

  • Success: 200 OK - Returns the generated NACHA file
  • Content-Type: text/plain
  • Content-Disposition: attachment; filename=nacha_file.txt

Error Responses

  • 400 Bad Request: Invalid input data
  • 415 Unsupported Media Type: Request is not JSON
  • 500 Internal Server Error: Server error while processing request

POST /api/v1/nacha/validate

Validates NACHA file data without generating a file.

Request

  • Content-Type: application/json
  • Body: Same format as the generate endpoint

Response

  • Success: 200 OK
  • Content-Type: application/json
  • Body: {"valid": true, "message": "NACHA data validation successful"}

Error Responses

  • 400 Bad Request: Validation failed
  • Body: {"valid": false, "error": "NACHA validation failed", "details": [...]}

Request Format

The API expects a JSON object with the following structure:

{ "file_header": { // File header fields }, "batches": [ { "batch_header": { // Batch header fields }, "entries": [ { // Entry detail fields "addenda": [ { // Addenda fields } ] } ] } ] }

File Header Fields

The file header record contains information about the origin and destination of the file.

Field Required Description Format/Values
immediate_destination Yes Routing number of the ACH Operator or receiving point 9 digits, can have a leading space
immediate_origin Yes Routing number or other identifier of the originating institution 9 digits, can have a leading space
file_creation_date No Date the file was created YYMMDD format (defaults to current date)
file_creation_time No Time the file was created HHMM format (defaults to current time)
file_id_modifier No Distinguishes between multiple files created on same date A-Z, 0-9 (defaults to 'A')
record_size No Size of each record 094 (default)
blocking_factor No Number of records in a block 10 (default)
format_code No Format code 1 (default)
immediate_destination_name No Name of the destination institution Up to 23 characters
immediate_origin_name No Name of the originating institution Up to 23 characters
reference_code No Reference code for the file Up to 8 characters

Batch Header Fields

Each batch header record contains information about a group of related entries.

Field Required Description Format/Values
service_class_code Yes Code indicating the type of entries in the batch 200, 220, or 225
company_name Yes Name of the company/organization Up to 16 characters
company_discretionary_data No For discretionary use Up to 20 characters
company_id Yes Company identification number Up to 10 characters
standard_entry_class Yes Code identifying the type of entries PPD, CCD, CTX, etc.
company_entry_description Yes Description of the entries Up to 10 characters
company_descriptive_date No Descriptive date for the company YYMMDD format
effective_entry_date No Date the entries should be settled YYMMDD format
settlement_date No Settlement date filled by ACH Operator 3 characters
originator_status_code No Code identifying the status of the originator 1 (default)
originating_dfi_id Yes Routing number of the originating institution 9 digits
batch_number No Batch sequence number Up to 7 digits

Entry Detail Fields

Each entry detail record contains information about an individual transaction.

Field Required Description Format/Values
transaction_code Yes Code identifying the type of transaction 22 (checking credit), 27 (checking debit), etc.
receiving_dfi_id Yes Routing number of the receiving institution (including check digit) 9 digits (complete routing number)
dfi_account_number Yes Account number at the receiving institution Up to 17 characters
amount Yes Amount of the transaction in cents Up to 10 digits (e.g., 100000 = $1,000.00)
individual_id No Identification number for the individual Up to 15 characters
individual_name Yes Name of the individual Up to 22 characters
discretionary_data No For discretionary use Up to 2 characters
trace_number No Unique identifier for the transaction Up to 15 digits
addenda No Array of addenda records See Addenda Records section

Addenda Records

Addenda records provide additional information related to an entry detail record.

Field Required Description Format/Values
addenda_type_code No Type of addenda record 05 (default)
payment_related_info Yes Additional information about the payment Up to 80 characters
addenda_sequence_number No Sequence number for multiple addenda records Up to 4 digits (defaults to 1)

Examples

Basic Example

This example creates a simple NACHA file with one batch containing one entry:

{ "file_header": { "immediate_destination": "123456789", "immediate_origin": "987654321", "file_creation_date": "210917", "file_creation_time": "1527", "file_id_modifier": "A", "immediate_destination_name": "DESTINATION BANK", "immediate_origin_name": "ORIGIN COMPANY" }, "batches": [ { "batch_header": { "service_class_code": "200", "company_name": "COMPANY ABC", "company_id": "1234567890", "standard_entry_class": "PPD", "company_entry_description": "PAYROLL", "effective_entry_date": "210920", "originating_dfi_id": "123456789", "batch_number": "1" }, "entries": [ { "transaction_code": "22", "receiving_dfi_id": "987654321", "dfi_account_number": "123456789", "amount": "100000", "individual_id": "EMP123", "individual_name": "JOHN DOE", "trace_number": "123456780000001" } ] } ] }

Complex Example

This example creates a NACHA file with multiple batches and entries, including addenda records:

{ "file_header": { "immediate_destination": "123456789", "immediate_origin": "987654321", "file_creation_date": "210917", "file_creation_time": "1527", "file_id_modifier": "A", "immediate_destination_name": "DESTINATION BANK", "immediate_origin_name": "ORIGIN COMPANY" }, "batches": [ { "batch_header": { "service_class_code": "200", "company_name": "COMPANY ABC", "company_id": "1234567890", "standard_entry_class": "PPD", "company_entry_description": "PAYROLL", "effective_entry_date": "210920", "originating_dfi_id": "123456789", "batch_number": "1" }, "entries": [ { "transaction_code": "22", "receiving_dfi_id": "987654321", "dfi_account_number": "123456789", "amount": "100000", "individual_id": "EMP123", "individual_name": "JOHN DOE", "trace_number": "123456780000001", "addenda": [ { "payment_related_info": "Employee ID: 12345, Pay Period: 09/01/2021-09/15/2021" } ] }, { "transaction_code": "22", "receiving_dfi_id": "876543219", "dfi_account_number": "987654321", "amount": "150000", "individual_id": "EMP456", "individual_name": "JANE SMITH", "trace_number": "123456780000002" } ] }, { "batch_header": { "service_class_code": "225", "company_name": "COMPANY ABC", "company_id": "1234567890", "standard_entry_class": "CCD", "company_entry_description": "VENDOR PAY", "effective_entry_date": "210920", "originating_dfi_id": "123456789", "batch_number": "2" }, "entries": [ { "transaction_code": "27", "receiving_dfi_id": "765432109", "dfi_account_number": "543210987", "amount": "250000", "individual_id": "VEND123", "individual_name": "ACME SUPPLIES", "trace_number": "123456780000003" } ] } ] }

NACHA Format Overview

NACHA files consist of fixed-width records in a specific format. Each record is exactly 94 characters long. The file has a hierarchical structure:

  • File Header Record - Contains information about the entire file (1 per file)
  • Batch Header Record - Contains information about a batch of entries (1 per batch)
  • Entry Detail Record - Contains information about an individual transaction (multiple per batch)
  • Addenda Record - Contains additional information about an entry (optional, multiple per entry)
  • Batch Control Record - Contains totals for the batch (1 per batch, automatically generated)
  • File Control Record - Contains totals for the file (1 per file, automatically generated)

The API automatically generates the control records based on the data provided. It also handles padding the file with "9" records to ensure the file contains a multiple of 10 records as required by the NACHA format.

Important: NACHA files are typically validated by the receiving financial institution. Ensure that your data is accurate and follows the NACHA specifications.