The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
ACH-Builder-0.20
River stage zero No dependents
/ ACH::Builder

NAME

ACH::Builder - Tools for building ACH (Automated Clearing House) files

SYNOPSIS

  use ACH::Builder;

  my $ach = ACH::Builder->new( {
      # Required
      company_id        => '11-111111',
      company_name      => 'MY COMPANY',
      entry_description => 'TV-TELCOM',
      destination       => '123123123',
      destination_name  => 'COMMERCE BANK',
      origination       => '12312311',
      origination_name  => 'MYCOMPANY',

      # Optional
      company_note      => 'BILL',
      effective_date    => '130903',
  } );

  # load some sample records
  my @samples = $ach->sample_detail_records;

  # build file header record
  $ach->make_file_header_record;

  # build batch for web entries
  $ach->set_entry_class_code( 'WEB' );
  $ach->make_batch( \@samples );

  # build batch for telephone entries
  $ach->set_entry_class_code( 'TEL' );
  $ach->make_batch( \@samples );

  # build file control record
  $ach->make_file_control_record;

  print $ach->to_string;

DESCRIPTION

This module is tool to help construct ACH files, which are fixed-width formatted files accpected by most banks. ACH (Automated Clearing House) is an electronic banking network operating system in the United States. ACH processes large volumes of both credit and debit transactions which are originated in batches. Rules and regulations governing the ACH network are established by the National Automated Clearing House Association (NACHA) and the Federal Reserve (Fed).

ACH credit transfers include direct deposit payroll payments and payments to contractors and vendors. ACH debit transfers include consumer payments on insurance premiums, mortgage loans, and other kinds of bills.

CONFIGURATION

The parameters below can be passed to the constructor new in a hashref.

company_id

Required. Your 10-digit company number; usually your federal tax ID.

company_name

Required. Your company name to appear on the receiver's statement; up to 16 characters.

entry_description

Required per batch. A brief description of the nature of the transactions. This will appear on the receiver's bank statement. Maximum of 10 characters.

destination

Required per file. The 9-digit routing number for the destination bank.

destination_name

Optional per file. A 23-character string identifying the destination bank.

origination

Required per file. This will usually be the same as the company_id.

origination_name

Required per file. This will usually be the same as the company_name, but note that it can be up to 23 characters long.

company_note

Optional per batch. For your own internal use. Maximum 20 characters.

effective_date

Optional per batch. Date in yymmdd format that the transactions should be posted.

DETAIL RECORD FORMAT

The make_batch function expects entry detail records in this format:

 {
   customer_name    => 'JOHN SMITH',   # Maximum of 22 characters
   customer_acct    => '0000-0111111', # Maximum of 15 characters
   amount           => '2501',         # In whole cents; this is $25.01
   routing_number   => '10010101',     # 9 digits
   bank_account     => '103030030',    # Maximum of 17 characters
   transaction_code => '27',
   entry_trace      => 'ABCDE0000000001', # Optional trace number
 }

Only the following transaction codes are supported:

 22 - Deposit to checking account
 27 - Debit from checking account
 32 - Deposit to savings account
 37 - Debit from savings account

Rules for the entry_trace may vary. An example institution requires the first 8 characters be the destination bank's routing number (excluding the final checksum digit), and the next 7 characters be a zero-filled number incrementing sequentially for each record.

METHODS

new({ company_id => '...', company_note ... })

See above for configuration details. Note that the configuration parameter names do not always match the names of the setter methods below.

make_file_header_record( )

Adds the file header record. This can only be called once and must be called before any batches are added with make_batch.

sample_detail_records( )

Returns a list of sample records ready for make_batch. See above for format details.

make_batch( @$records )

Adds a batch of records to the file. You must have called make_file_header_record before adding a batch to the file.

make_file_control_record( )

Adds the file control record, finishing the file. This can only be called once. Afterward, the ACH file can be retrieved in its entirety with to_string.

format_rules( )

Returns a hash of ACH format rules. Used internally to generate the fixed-width format required for output.

to_string( )

Returns the built ACH file.

ach_data( )

Returns as an arrayref the formatted lines that will be turned into the ACH file.

set_origin_status_code( $value )

The code must be either:

 1 - Originator is a financial institution bound by the NACHA rules (the default)
 2 - Originator is a federal agency not bound by the NACHA rules

set_format_code( $value )

Of limited value. The only valid format code is 1, the default.

set_blocking_factor( $value )

Of limited value. The only valid blocking factor is 10, the default.

set_record_size( $value )

Of limited value. The only valid record size (characters per line) is 94, the default.

set_file_id_modifier( $value )

A sequential alphanumeric value used to distinguish files submitted on the same day. The default is A.

set_immediate_origin_name( $value )

The same as the origination_name described above. This will usually be your company name and is limited to 23 characters.

set_immediate_origin( $value )

The same as the origination described above. This will usually be your federal tax ID number, in ##-####### format.

set_immediate_dest_name( $value )

The same as the destination_name described above. This identifies the destination bank that will be processing this file. Limited to 23 characters.

set_immediate_dest( $value )

The same as the destination described above. This is the 9-digit routing number of the destination bank.

set_entry_description( $value )

A brief description of the nature of the transactions. This will appear on the receiver's bank statement. Maximum of 10 characters. This can be set separately for each batch before make_batch is called.

set_entry_class_code( $value )

The code must be one of:

 PPD - Prearranged Payments and Deposit entries for consumer items (the default)
 CCD - Cash Concentration and Disbursement entries
 CTX - Corporate Trade Exchange entries for corporate transactions
 TEL - Telephone initiated entries
 WEB - Authorization received via the Internet

set_company_id( $value )

Your 10-digit company number; usually your federal tax ID. This can be set separately for each batch.

set_company_name( $value )

Required. Your company name to appear on the receiver's statement; up to 16 characters.

set_company_note( $value )

An optional parameter for your internal use, limited to 20 characters.

set_effective_date( $value )

The date that transactions in this batch will be posted. The date should be in YYMMDD format. Defaults to tomorrow.

set_service_class_code( $value )

The code must be one of:

 200 - Mixed credits and debits (the default)
 220 - Credits only
 225 - Debits only

NOTES

The ACH record format is officially documented in the NACHA Operating Rules & Guidelines publication, which is not freely available. It can be purchased at: https://www.nacha.org/achrules

ACH file structure:

 File Header
   Batch Header
     Entries
   Batch Control
   Batch Header
     Entries
   Batch Control
  File Control

LIMITATIONS

Only certain types of ACH transactions are supported (see the detail record format above).

AUTHOR

Tim Keefer <tkeefer@gmail.com>

CONTRIBUTORS

  • Cameron Baustian <camerb@cpan.org>

  • Steven N. Severinghaus <sns-perl@severinghaus.org>

COPYRIGHT

Tim Keefer, Cameron Baustian