Payment - Batch (ABA file format)
An .ABA file is an electronic file format commonly used by Australian banks for processing bulk transactions, such as payroll, accounts payable, and direct debits. It's structured in a format specified by the Australian Banking Association (ABA) and adheres to a standard known as the Direct Entry (DE) file format.
Specification
Each line in an ABA file is a record. An ABA file includes three main record types:
- Descriptive Record (Header)
- Detail Record (for each transaction)
- File Total Record (Summary)
Each ABA record is exactly 120 characters long and must be separated by a carriage-return/line-feed (CRLF).
Allowed Character Set
- Letters: A-Z, a-z
- Numbers: 0-9
- Special Characters:
space,&,',,,-,.,/,+,$,!,%,(,),*,#,=,:,?,[,],_,^,@ - Optional Alphanumeric Fields: Fill with spaces if no data exists.
- Numeric Fields: Use only numbers (0-9) and fill with zeros if optional and no data exists.
Record Specifications
1. Descriptive Record (Type 0)
This header provides general information about the file.
| Char Pos | Field Size | Field Description | Specification |
|---|---|---|---|
| 1 | 1 | Record Type | Must be '0' |
| 2-18 | 17 | Blank | Must be filled |
| 19-20 | 2 | Sequence Number | Must be '01'. Right justified, zero-filled |
| 21-23 | 3 | Financial Institution | Abbreviation of User’s FI |
| 24-30 | 7 | Blank | Must be blank filled |
| 31-56 | 26 | Name of User | As specified by FI. Left justified, blank filled |
| 57-62 | 6 | User ID Number | Allocated by FI. Numeric, right justified, zero-filled |
| 63-74 | 12 | Description (e.g., "PAYROLL") | All character set valid. Left justified, blank filled |
| 75-80 | 6 | Processing Date | Format DDMMYY. Zero-filled |
| 81-120 | 40 | Blank | Must be blank filled |
2. Detail Record (Type 1)
Each detail record contains specific transaction details.
| Char Pos | Field Size | Field Description | Specification |
|---|---|---|---|
| 1 | 1 | Record Type | Must be '1' |
| 2-8 | 7 | Bank/State/Branch (BSB) Number | Must be numeric with hyphen in position 5 |
| 9-17 | 9 | Account Number | Right justified, blank filled |
| 18 | 1 | Indicator | 'N' for new/varied BSB; 'W', 'X', 'Y' for withholding tax |
| 19-20 | 2 | Transaction Code | e.g., '13' for Debit, '50' for Credit |
| 21-30 | 10 | Amount | In cents, right justified, zero filled |
| 31-62 | 32 | Account Title | Left justified, blank filled |
| 63-80 | 18 | Lodgement Reference | Left justified, no leading characters |
| 81-87 | 7 | Trace BSB | Format xxx-xxx |
| 88-96 | 9 | Trace Account Number | Right justified, blank filled |
| 97-112 | 16 | Name of Remitter | Left justified, blank filled |
| 113-120 | 8 | Withholding Tax Amount | In cents, right justified, zero filled |
3. File Total Record (Type 7)
This record provides totals for reconciliation purposes.
| Char Pos | Field Size | Field Description | Specification |
|---|---|---|---|
| 1 | 1 | Record Type | Must be '7' |
| 2-8 | 7 | BSB Format Filler | Must be '999-999' |
| 9-20 | 12 | Blank | Must be blank filled |
| 21-30 | 10 | File Net Total Amount | Right justified, zero filled |
| 31-40 | 10 | File Credit Total Amount | Accumulated total of credit Detail Records |
| 41-50 | 10 | File Debit Total Amount | Accumulated total of debit Detail Records |
| 51-74 | 24 | Blank | Must be blank filled |
| 75-80 | 6 | Total count of Record Type 1 items | Right justified, zero filled |
| 81-120 | 40 | Blank | Must be blank filled |
Filename journey
| Step | Action | Example Filename #1 |
|---|---|---|
| 1. | File is uploaded to SFTP server | 19-3-2024.aba |
| 2. | When Azupay Batch app picks up the file, we rename it to: | 19-3-2024.processing.aba |
| 3. | When an error occurs processing the file, we will rename to: | 19-3-2024.error.aba |
Will also create 19-3-2024-response.aba file containing the error message, examples: | ||
- Mismatch error: sum of all transactions | ||
- Mismatch error: count of all transactions | ||
- Data error: invalid format | ||
- Data error: count of transactions exceeds maximum allowed (100,000) | ||
- Error: filename <...> not valid ... | ||
| - or exception message from parser | ||
| 4. | When file is succeessfully processed by the Azupay Batch app, we will rename to: | 19-3-2024.processed.aba |
File error handling
File Error defines errors that were encountered when parsing the submitted ABA file.
- The response file will be generated with the error messages in the content.
- No outbound payments were sent
| Error | Failures | Reattempt / Redrive actiond |
|---|---|---|
| Sum of all "credit" transactions (record with TX code "50") does not match with "File Credit Total Amount (from footer / record 7) | - Failure for all transactions, no payment made | - Merchant can "fix" the file and re-upload |
- Original file renamed to ...-error.aba | - Merchant can use the same filename or a new filename | |
- Error message created in file ...-response.aba | ||
| Count of all transactions does not match with "Total count of Records" (from footer / record 7) | - Failure for all transactions, no payment made | - Merchant can "fix" the file and re-upload |
- Original file renamed to ...-error.aba | - Merchant can use the same filename or a new filename | |
- Error message created in file ...-response.aba | ||
| File cannot be parsed | - Failure for all transactions, no payment made | - Merchant can "fix" the file and re-upload |
- Original file renamed to ...-error.aba | - Merchant can use the same filename or a new filename | |
- Error message created in file ...-response.aba | ||
| Filename not valid | - Failure for all transactions, no payment made | - Merchant can "fix" the file and re-upload |
Due to concatenation of filename (without extension) and transaction/row number for clientPaymentId, it must be a valid clientPaymentId. | - Original file renamed to ...-error.aba | - Merchant can use the same filename or a new filename |
- Error message created in file ...-response.aba |
Idempotency
An idempotency key is something we use to prevent duplicate processing of the same transaction. For each transaction, we create a unique key using the filename and the row number of the transaction in that file. This key helps the system identify each transaction, even if there are repeated attempts to process it.
The idempotency key used for the idempotent field (Payment.clientPaymentId) is structured as:
<filename><dash><row-number>
Example Values:
3-24-2024-1(first transaction in file3-24-2024.aba)3-24-2024-2(second transaction in file3-24-2024.aba)- …and so on.
Refer to API reference documentation here for further information on Payment.clientPaymentId: https://developer.azupay.com.au/reference/makepayment
It is important for file that is successfully processed, that you DO NOT rename and re-upload the file as it will be treated as new transactions.
Updated about 2 months ago