The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
ACH-Builder-0.23
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',
      allow_unbalanced_file => 1,
  } );

  # 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;

  # add 9's filler records as needed
  $ach->make_filler_records;

  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.

originating_dfi

Optional per file. This will usually be the first 8 positions of origination, but it can be set specifically if a certain originating Depository Financial Institution is needed.

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.

creation_date

Optional per batch. Date in yymmdd format that the transactions were created on. Useful when needing to re-create files exactly as they were originally created. Defaults to current date.

creation_time

Optional per batch. Time in HHMM format that the transactions were created at. Useful when needing to re-create files exactly as they were originally created. Defaults to current time.

allow_unbalanced_file

Optional per file. 1=True, 0=False. Allows for a file to contain debits and credits that don't net to 0. The default is 0. 0 is useful for using the file to transfer funds and 1 is useful when only doing debits (billing for services) or credits (refunding transactions, distributing funds).

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
   addenda          => [               # optional addenda entries
     {
       addendum_code => '05',
       addendum_info => 'TEST INFO',
     },
   ],
 }

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.

make_filler_records( )

Adds filler records (all 9's) as needed to fill out last block, so that the total number of records is a multiple of 10.

format_rules( )

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

to_string([$line_term])

Returns the built ACH file. $line_term is added to each line (default "\n")

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_originating_dfi( $value )

The same as the originating_dfi described above, Originating DFI Identification. This will default to the first 8 positions of origination unless otherwise specified.

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_creation_date( $value )

The date that transactions in this batch were created. The date should be in YYMMDD format. Defaults to today.

set_creation_time( $value )

The time that transactions in this batch were created. The time should be in HHMM format. Defaults to now.

set_allow_unbalanced_file( $value )

Allow for a file's credits and debits to be unbalanced. Default is false.

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).

ENCODING

The ACH file format only supports ASCII characters. All data is converted to ASCII using Encode::encode(). Any non-ASCII characters in the input are replaced with a substitution character ("?").

AUTHOR

Tim Keefer <tkeefer@gmail.com>

CONTRIBUTORS

  • Cameron Baustian <camerb@cpan.org>

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

COPYRIGHT

Tim Keefer, Cameron Baustian