The ABA file format, sometimes called Direct Entry or Cemtext, is an unpublished de facto standard for bulk electronic payments. It is used by all major Australian financial institutions to interface with business accounting systems, and is supported by many popular accounting packages such as MYOB. For small-to-medium businesses, the most common usage for an ABA file is to upload it via their Internet banking portal – to avoid manually entering transaction details into the web application. As the name suggests, the format is dictated by the Australian Banking Association, and also has ties with the Australian Payments Clearing Association (APCA).
I was recently tasked with writing an exporter from a proprietary, relational database system to the ABA format. Since the specifications for the file format are not in the public domain (at least, not from an official source), I had to rely on some third-party sources to arrive at a solution. In this article, i’ll share those resources with you, as well as providing my own explanation of some of the finer points of the standard – to help you avoid common pitfalls when working with the format.
Overview of the ABA format
The ABA format is somewhat archaic; certainly based on outdated technology. It’s a plain-text format that uses fixed-width fields (most of which are severely constrained, to the point that most data going into them must be truncated or abbreviated in order to fit). It is not supposed to be human-readable, although a trained eye can interpret it. Its values are untyped and there is nothing to validate the correctness of an ABA file if you are not privy to the rules.
An ABA file consists of:
- One ‘type 0’ record (i.e. line) which describes and provides instructions processing instructions for the batch
- One or more ‘type 1’ records which provide the detail for each payment in the batch
- One ‘type 7’ record which confirms the size and totals for the batch
(i.e. an ABA file is at least 3 lines long.)
Within each record/line in the file, and depending on the record type, there are a number of fixed-width fields which must be populated. Some are padded with zeroes, others with spaces. Some occupy the left portion of the field, others (like numeric fields) are right-justified. A complete line must consist of exactly 120 characters (excluding the CR/LF terminator). It’s helpful to write a function to perform the necessary padding/truncation and justification:
// requires a reference to System.Linq string ToFixedWidth(string input, int length, char padding = ' ', bool rightJustify = false) { char[] output = new char[length]; if (rightJustify) input = new string(input.Reverse().ToArray()); for (int i = 0; i < length; i++) { if (i < input.Length) output[i] = input[i]; else output[i] = padding; } if (rightJustify) output = output.Reverse().ToArray(); return new string(output); } // to pad a string out to 18 characters, left-justified and padded with spaces: ToFixedWidth(str, 18); // to pad a decimal number out to 10 characters, right-justified and padded with zeroes: ToFixedWidth((num * 100).ToString("0000000000"), 10, '0', true);
Some additional notes:
- Most examples i’ve seen capitalise all text fields, however this is not necessary. Some financial institutions will retain the casing of your narrations/annotations, if only on the sender’s bank statement.
- All dollar amounts are expressed in whole cents, with no digit grouping. Multiply your decimal figures by 100 and use an appropriate number format string (e.g. “0000000000”).
Resources for the file format specification
The following are two excellent resources for the specification of the ABA file format itself:
- Blue Chilli’s specification for the ABA file format
- David Klein’s specification for the ABA file format
Between these two documents, you should have all the information you need to construct the ABA records themselves. There is some inherent ambiguity in these, however, which is why i’d like to add the following notes:
Descriptive record
Reel sequence number
There is a maximum number of payments you can include per ABA file, if only because the dollar amount and number of records fields are of a fixed length. If you need to split your batch into multiple files, the reel sequence number identifies each one. However, in the vast majority of cases, you will only have one file, numbered 01. You do not have to keep track of which numbers you have used previously.
User Preferred Specification
This is one of two pieces of information that identify the user and their financial institution. Some banks will dictate the value for this field, others are less restrictive and will permit any form of the name on the user’s bank account. It’s best to make the value for this field user-maintainable.
User Identification Number
Contrary to its description, this number identifies the financial institution, not the user. Each FI has its own number (or possibly several, depending on the size of the bank) which is issued by APCA. This number does not change between batches; it’s tied to the bank and, potentially, the account. Most banks document this number somewhere in their internet banking portal instructions.
Detail records
Indicator
As far as I can tell, this field can be used to indicate that a particular record represents a change to a prior record in the batch, or to existing details held on file for the payee. It’s also clear that not every financial institution pays attention to this field. Unless you are dealing with thousands of payments at a time, you should leave this field blank to make it clear that each record represents a separate payment.
Transaction code
In most cases, you should use the code 50, which represents a non-specific credit to the bank account. For payroll transactions, use the code 53. The other transaction codes appear to be of relevance to the ATO and superannuation funds only.
Lodgement reference
This is the text that appears on the payee’s bank statement.
Trace record (BSB and Account No)
This is the BSB and Account Number of your bank account.
Name of remitter
If your bank supports it, this lets you track the name of the person in your organisation who authorised the payment.
Final words
Hopefully, this points you in the direction of the right resources and helps to dispel some of the confusion surrounding the ABA file format. By following the specification exactly, you will produce a file that can be read by all major Australian banks and has the potential to save time and reduce errors when processing large numbers of payments.
See also
ABA/Cemtext Validator – An ABA file validator and SDK based on this article
i like to to talk to you about your blog postiong on .aba file , i like top seek some help on this
Chandra wasan
04070698942
Cosmic Acounting Group
Feel free to e-mail me with any specific questions you may have.
To let you have a little more information, the ABA file (also known as CS2) has the following record types: 0 – logical file header record, 1 – payment detail record, 2 – payment return record, 3 – payment refusal record, 7 – logical file trailer record, 9 – physical file termination record. There can be more than one logical file in a physical file. The type 9 record is optional; it is used by some banks only.
Regarding “the specifications for the file format are not in the public domain (at least, not from an official source)”, the specification from the Australian Payments Clearing Association (APCA) is at: http://www.apca.com.au/docs/payment-systems/becs_procedures.pdf
The file format is for banks to talk to each other, but banks have for whatever reason decided to adopt the same format for their users to request transactions.
Something that confused me about this file format is that each line is a credit or debit, not a transfer (i.e. both debit and credit). It does not have the concept of “from” and “to”. So, when you upload an ABA file to your bank to make payments, you are telling the bank where you want credits to appear (other people’s accounts) and what amount to credit, but you still need to tell them (outside of the file, i.e. in the graphical user interface) where that money should be drawn from (debit).
Pingback: Direct Debits with Salesforce — AAkonsult Payments
Cheers for this. I have to write an export for this format. It will be less of a ball-ache armed with this information
Since everyone seems to reinvent the wheel with writing their own ABA exporter, I’ve put up an open source MIT licensed ABA file format read/write library here: https://github.com/stuarta0/banking-au
Now you don’t need to worry about getting the right archaic format. The code uses FileHelpers to do the low-level read/write and the classes instantiate with the common defaults (as listed in the blog post above).
The intent is to provide further formats for AU banking needs in this library (such as Westpac QuickSuper). If you’re reading this and need to work with another format, by all means fork and send me pull requests 🙂
Developers can also use the author’s own SDK for this 🙂
Well how about that! I’d update the blog post to point to that article too since my searching didn’t come up with it 🙂 Based on the post I’d say the implementations are pretty similar, maybe I’ll pull your validation code in 😉
Hi Stuart that code looks good however do you have a sample of how you can validate the data coming, like Bradley Smith’s version of Validator.ValidateFile()?
thanks
You are the man! Saved me some time and a headache or two I bet. Cheers
Regarding the aba format I set one up in a Dos database and it worked.
Now i have migrated to excel i notice that the header and footer that require “blanks” on the right fill do not accept the space character for the aba file to work.
Spaces elsewhere in the file are recognized.
I checked back what I used in Dos and I used CHR(225) as the fill.
I presume I will need to do the same.ie. not the space character under VB excel.
I’ve never encountered any problems with using space characters where the specification requires “blanks”. Could it be that Excel is trimming whitespace from your files?
I don’t think it is. I have checked the length of each field including header and footer of the file and they are each 120 characters wide., but I dont know exactly what happens after I convert it to a CSV type file..it “looks” ok.
I will let you know tomorrow about CHR(225) if that solves the problem.
Thanks for the post and other peoples comments. I am developing an extract for ABA BECS for our Australian branches.
Hi, Bradley.
Thanks for the utility.
AbaFile.cs has a syntax error at Line 247, Col154 – Brace comes after bracket resulting in invalid format string.
Regards.
Ah, thanks for pointing this out. I will release an updated version of the source and binaries soon.
Hi Bradley,
The link is broken. Blue Chilli’s specification for the ABA file format
Regards,
It’s moved to a new location.
It seems that ABA file is ASCII however the NAB uses BECS files in EBCDIC.
Have the Australian banks got two separate methods or are ABA files dead now?
I wrote ABA for several banks a few years back and each had its own rules.
I’ve looked at the NAB specs and the files still use ASCII encoding, however only a limited range of characters are considered valid (presumably to ensure compatibility with back-end systems that still use EBCDIC). This is no different for the other banks; the valid characters are described in the ABA specs and not by any one financial institution.
ABA is still very much alive, although I am hopeful that the roll-out of the New Payments Platform (PayID/Osko) will give us a more modern alternative such as JSON or XML.
Hi Bradley,
Thank so much for this article.
In the File Total Record (7) that comes at the do of the file, can you kindly clarify the below
File (User) Credit Total Amount – Numeric only valid.
Must equal the accumulated total of credit Detail Record amounts. Show in cents without punctuation. Right justified, zero filled. Unsigned.
Should this field have the amount that goes out of my bank account or the amount that comes in to my bank account?
Thanks!
This is the total amount that goes out of your bank account (ABA files can only be used for recording outgoing payments). It’s simply the total of all the amounts in the Type 1 records.
It is the total of the credit transactions. Transaction codes: 50 to 57.
Debit transactions use transaction code 13.
Total amount is the difference between both, so hence a self balancing file will have a nett balance of zero.
Hey
Would you know if the DE File Format allows for multiple File Total Records (Type 7) in a single file? Unable to find this specific information in any of the public domain material that I have gone through.
If e.g., I have three records at the end of a file starting with 7999-999, followed by valid entries into character positions 9 through to 120, would this file be valid and successfully processed?
Short answer is “I don’t know”. My interpretation of the specifications is that each file should have only one type 0 record at the beginning of the file, and one type 7 record at the end of the file.
I think it will depend on the individual bank as to how additional type 7 records would be treated.
It seems like there is a more recent fork of Stuart’s original github ABA generator:
https://github.com/andrensairr/banking-au/commits/master