# ABA File Format and Processing Guide Complete specification for ABA format outbound payment files, including record structure, validation rules, processing lifecycle, response files, and error handling. # 1. File Processing Guide ## 1.1 Purpose This guide explains how files submitted through Azupay Batch are processed, from submission through to response file generation. It covers the ABA file format for outbound payments, the complete processing lifecycle including file states and naming conventions, response file formats and timing expectations, and how to distinguish file-level validation failures from transaction-level failures. After reading this guide, you will understand what happens after you submit a file via SFTP, how to interpret the response files that Azupay generates, and where to find detailed transaction outcomes in the Dashboard. For SFTP connectivity setup, SSH key configuration, and network requirements, see the Connectivity Guide (./connectivity-guide.md). ## 1.2 Supported File Formats ### 1.2.1 ABA Format (Outbound Payments) #### 1.2.1.1 Overview ABA (Australian Bankers Association format, also called Cemtex) is a fixed-width file format used for bulk payment processing in Australia. Each line is exactly 120 characters, terminated with CRLF (`\r\n`). Files contain three record types: a descriptive header (type 0), one or more detail records (type 1) for individual payments, and a file trailer (type 7) with control totals. #### 1.2.1.2 Record Structure **Record Type 0 (Descriptive/Header) - 120 characters:** * Position 1: `0` (record type) * Positions 2-18: Blank (17 spaces) * Positions 19-20: Reel sequence number (e.g., `01`) * Positions 21-23: Financial institution code (e.g., `CBA`) * Positions 24-30: Blank (7 spaces) * Positions 31-56: User Name (26 characters) * Positions 57-62: User ID (6 characters) * Positions 63-74: Description (12 characters) * Positions 75-80: Processing date DDMMYY * Positions 81-120: Blank (40 spaces) **Record Type 1 (Detail/Transaction) - 120 characters:** * Position 1: `1` (record type) * Positions 2-8: BSB of credit account (format: XXX-XXX) * Positions 9-17: Account number (9 characters, right-justified, space-padded) * Position 18: Indicator (space, `N`, `W`, `X`, or `Y`) * Positions 19-20: Transaction code (e.g., `50` = credit, `53` = debit) * Positions 21-30: Amount in cents (10 digits, zero-padded) * Positions 31-62: Title of account (32 characters) * Positions 63-80: Lodgement reference (18 characters) * Positions 81-87: Trace BSB (originating account, format: XXX-XXX) * Positions 88-96: Trace account number (9 characters) * Positions 97-112: Name of remitter (16 characters) * Positions 113-120: Withholding tax amount (8 digits, typically zeros) **Record Type 7 (File Trailer) - 120 characters:** * Position 1: `7` (record type) * Positions 2-8: `999-999` (filler BSB) * Positions 9-20: Blank (12 spaces) * Positions 21-30: File net total in cents (10 digits, zero-padded) * Positions 31-40: File credit total in cents (10 digits, zero-padded) * Positions 41-50: File debit total in cents (10 digits, zero-padded) * Positions 51-74: Blank (24 spaces) * Positions 75-80: Count of type 1 records (6 digits, zero-padded) * Positions 81-120: Blank (40 spaces) #### 1.2.1.3 Example ABA File ``` 0 01CBA Local Pegs Pty Ltd 301500Pegs Withdra030924 1012-003838337977 500000137134Sunrise Hotels Pty Ltd 030920241 062-692 49705956Pegs 00000000 1062-692 70325640 500000046094Saclike Trading Co 030920242 062-692 49705956Pegs 00000000 1062-000 12345678 500000000100Failed by Cuscal Pty Ltd 030920254 062-684 49705004Pegs 00000000 7999-999 000018332800001833280000000000 000003 ``` This file instructs three outbound credit payments totalling $1,833.28 from Local Pegs Pty Ltd (originating account BSB 062-692, account 49705956): * $1,371.34 to Sunrise Hotels Pty Ltd (BSB 012-003, account 838337977) * $460.94 to Saclike Trading Co (BSB 062-692, account 70325640) * $1.00 to Failed by Cuscal Pty Ltd (BSB 062-000, account 12345678) — a test transaction designed to fail #### 1.2.1.4 Validation Rules File-level validation failures prevent processing and result in no PROCESSED response file: * Invalid ABA format (incorrect record types, malformed fields, wrong line length) * File corruption or encoding issues (non-ASCII characters, truncated records) * Empty files or files with no detail records * Trailer totals that do not match the sum of detail record amounts * Trailer record count that does not match the number of type 1 records Transaction-level validation failures do not prevent processing; the file reaches PROCESSED state and failures are reported as aggregate counts in the Summary Response File: * Invalid BSB format or non-existent BSB * Invalid account number or closed account * Insufficient funds in originating account * Payment amount outside allowed limits #### 1.2.1.5 Character Encoding ABA files must use ASCII encoding. Non-ASCII characters in account names, references, or other text fields may cause file-level validation failures. ### 1.2.2 File Naming Requirements ABA outbound payment files must follow a specific naming convention for successful processing. #### 1.2.2.1 Naming Format ``` payment.aba ``` Where: * `` and `` can each be either a hyphen (`-`) or underscore (`_`) * `` contains only digits (0-9) * `` can contain any characters **Components:** | Component | Description | Rules | | --- | --- | --- | | `payment` | File type indicator | Must be `payment` (lowercase) for outbound payments | | Separator 1 | Delimiter | Must be either hyphen (`-`) or underscore (`_`) | | Numeric ID | Unique batch identifier | Digits only (0-9); must be unique for deduplication | | Separator 2 | Delimiter | Must be either hyphen (`-`) or underscore (`_`) | | Suffix | Additional identifier | Any characters; used for description or versioning | | `.aba` | File extension | Must be `aba` for ABA format files | #### 1.2.2.2 Examples Valid filenames: ``` payment_20251109_batch.aba payment-20251109-batch.aba payment_001_payroll.aba payment-001-payroll.aba payment_20251109_FILE.aba payment_20251109-production.aba payment_123_test-run-v2.aba payment-456_ACMECorp.aba payment_789_.aba payment_20251109_v1-final.aba ``` #### 1.2.2.3 File-ID Guidelines The numeric ID portion (between the first and second separators) serves as your unique batch identifier for deduplication: * Must contain only numeric characters (digits 0-9) * Must be unique to distinguish batches and enable deduplication * Commonly uses date formats (YYYYMMDD), sequential numbers, or timestamps * The suffix after the second separator can contain any characters for additional context #### 1.2.2.4 Invalid Filenames The following will cause processing failures: ``` outbound_20251109_batch.aba # Incorrect file-type (must be "payment") Payment_20251109_batch.aba # Incorrect case (must be lowercase "payment") PAYMENT_20251109_batch.aba # Incorrect case (must be lowercase "payment") payment20251109batch.aba # Missing separators payment_batch_20251109.aba # Numeric ID not in correct position payment_20251109.aba # Missing second separator and suffix payment__batch.aba # Missing numeric ID payment_abc_batch.aba # Non-numeric ID (contains letters) payment-20251109.txt # Incorrect extension (must be "aba") ``` ## 1.3 File Submission and Processing Lifecycle ### 1.3.1 Submission Upload your ABA file to the configured location via SFTP: * **Azupay Hosted SFTP Server:** Upload to the UPLOAD\_FOLDER assigned by the Azupay Support Team during onboarding. * **Customer Hosted SFTP Server:** Place the file in the FOLDER you configured in the Dashboard. For connection details and SFTP commands, see the Connectivity Guide sections 1.3.1 and 1.3.2. ### 1.3.2 File Pickup (Polling) Azupay polls for new files every 1 minute. Once a file is detected, it is picked up for processing. Polling frequency is the same for both Azupay Hosted and Customer Hosted connectivity models. ### 1.3.3 RECEIVED State Within 0 to 90 seconds of file pickup, Azupay generates a Summary Response File with `_RECEIVED` in the filename. This file confirms that your file was picked up by the polling process. The RECEIVED response file uses a fixed template and does not indicate whether the file passed validation; all transaction counts and amounts are shown as zero at this stage. The RECEIVED response file appears in a `response/` subdirectory relative to the directory where you placed the input file. ### 1.3.4 Processing After the RECEIVED response file is generated, Azupay renames the original file by inserting `.processing.` before the file extension. For example, `payment-request.aba` becomes `payment-request.processing.aba`. This happens in the original upload location. If you list files during this brief window, you will see the `.processing.` file instead of the original filename. Azupay then validates the file format and, if valid, processes the individual transactions. Processing time varies based on the number of transactions in the file. ### 1.3.5 PROCESSED State (Success Path) If file-level validation succeeds, Azupay generates a Summary Response File with `_PROCESSED` in the filename. This file contains aggregate counts and totals for successful and failed transactions. The PROCESSED response file appears in the same `response/` subdirectory as the RECEIVED file. The original file is moved to an `archive/` subdirectory (alongside `response/`) and renamed by replacing `.processing.` with `.processed.` in the filename. For example, `payment-request.processing.aba` becomes `payment-request.processed.aba` in the `archive/` directory. ### 1.3.6 Failure Path (File Rejection) If file processing fails due to validation errors, decryption failures, or complete parsing failures, no PROCESSED response file is generated. Instead, Azupay generates a Summary Response File with `_REJECTED` in the filename containing error details about why the file was rejected. The REJECTED response file appears in the same `response/` subdirectory as the RECEIVED file. The original file is moved to the `archive/` subdirectory and renamed by replacing `.processing.` with `-error.` in the filename. For example, `payment-request.processing.aba` becomes `payment-request-error.aba` in the `archive/` directory. To determine the cause of the failure, check the REJECTED response file for error details, or check the Dashboard or contact support@azupay.com.au with the filename, timestamp, and environment (UAT or Production). ### 1.3.7 Directory Structure After Processing **Success path:** ``` UPLOAD_FOLDER/ (or FOLDER/) response/ payment-request_RECEIVED.txt payment-request_PROCESSED.txt archive/ payment-request.processed.aba ``` **Failure path:** ``` UPLOAD_FOLDER/ (or FOLDER/) response/ payment-request_RECEIVED.txt payment-request_REJECTED.txt archive/ payment-request-error.aba ``` ## 1.4 Response Files ### 1.4.1 Summary Response Files Azupay generates Summary Response Files for each submitted ABA file. All files receive a `_RECEIVED` status file confirming pickup. If file-level validation succeeds, a `_PROCESSED` status file is generated with processing results. If file-level validation fails, a `_REJECTED` status file is generated with error details. All response files are plain text files written to a `response/` subdirectory relative to the directory where you placed the input file. #### 1.4.1.1 RECEIVED Summary Response File The RECEIVED file confirms file pickup. It uses a fixed template with all transaction counts and amounts set to zero. The status is always `RECEIVED` with the message "The file has been received successfully." This file does not indicate whether validation passed or failed. **Filename format:** `_RECEIVED.txt` where `` is the original input filename without the `.aba` extension. **Example content:** ``` Azupay Status Message Client Name: client-account-full-legal-account-name Status Filename : payment-connectivity-test-1-request_RECEIVED.txt Status Creation Date : 18/09/25 Status Creation Time : 11:36 Transaction Reference : payment-connectivity-test-1-request.aba Status: RECEIVED The file has been received successfully. Filename : payment-connectivity-test-1-request.aba Description : Value Date : $Debits : 0.00 $Credits : 0.00 $Cheques : 0.00 #Payments : 0 #Advices : 0 #Records : 0 Thank you for using Azupay. ``` #### 1.4.1.2 PROCESSED Summary Response File The PROCESSED file contains aggregate results after transaction processing. It shows counts and totals for successful payments, returned (failed) payments, and the overall file totals. The status is `PROCESSED` with the message "The transaction has been processed." **Filename format:** `_PROCESSED.txt` where `` is the original input filename without the `.aba` extension. **Example content:** ``` Azupay Status Message Client Name: client-account-full-legal-account-name Status Filename : payment-connectivity-test-1-request_PROCESSED.txt Status Creation Date : 18/09/25 Status Creation Time : 11:37 Transaction Reference : payment-connectivity-test-1-request Status: PROCESSED The transaction has been processed. Filename : payment-connectivity-test-1-request Description : client-account-full-legal-account-name Value Date : 18/09/25 $Debits : 1833.28 $Credits : 1833.28 $Cheques : 0.00 $Returned Payments : 1.00 #Returned Payments : 1 #Payments : 2 #Advices : 0 #Records : 3 Thank you for using Azupay. ``` In this example: * **#Payments: 2** — two transactions settled successfully * **#Returned Payments: 1** — one transaction failed * **$Returned Payments: 1.00** — total amount of failed transactions * **#Records: 3** — total number of detail records in the original file The PROCESSED file shows **aggregate counts only**; it does not identify which specific transactions failed. #### 1.4.1.3 REJECTED Summary Response File The REJECTED file is generated when file processing fails due to validation errors, decryption failures, or complete parsing failures. It contains error details explaining why the file could not be processed. The status is `REJECTED` with a descriptive error message. **Filename format:** `_REJECTED.txt` where `` is the original input filename without the `.aba` extension. **Example content:** ``` Azupay Status Message Client Name: client-account-full-legal-account-name Status Filename : payment-connectivity-test-1-request_REJECTED.txt Status Creation Date : 18/09/25 Status Creation Time : 11:36 Transaction Reference : payment-connectivity-test-1-request.aba Status: REJECTED The transaction has been rejected. ERROR: Un-parseable file - payment-connectivity-test-1-request.aba. Data error: invalid format Filename : payment-connectivity-test-1-request.aba Description : Value Date : $Debits : 0.00 $Credits : 0.00 $Cheques : 0.00 #Payments : 0 #Advices : 0 #Records : 0 Thank you for using Azupay. ``` **Common rejection reasons:** * Invalid ABA format (incorrect record types, malformed fields, wrong line length) * File corruption or encoding issues (non-ASCII characters, truncated records) * Empty files or files with no detail records * Trailer totals that do not match the sum of detail record amounts * Trailer record count that does not match the number of type 1 records * File decryption failures (for encrypted files) * Complete file parsing failures (when all rows contain errors and no transactions can be processed) #### 1.4.1.4 Field Descriptions | Field | Description | | --- | --- | | Client Name | Your full legal account name as configured in Azupay | | Status Filename | Name of this response file | | Status Creation Date | Date the response file was generated (DD/MM/YY, Australia/Sydney timezone) | | Status Creation Time | Time the response file was generated (HH:MM, Australia/Sydney timezone) | | Transaction Reference | Original input filename or batch identifier | | Status | RECEIVED, PROCESSED, or REJECTED | | Filename | Original input filename or batch identifier | | Description | Client account name or file description | | Value Date | Processing date (PROCESSED files only) | | $Debits | Total debit amount (PROCESSED files only; typically matches $Credits for balanced files) | | $Credits | Total credit amount (PROCESSED files only) | | $Cheques | Total cheque amount (typically 0.00) | | $Returned Payments | Total amount of failed/returned transactions (PROCESSED files only) | | #Returned Payments | Count of failed/returned transactions (PROCESSED files only) | | #Payments | Count of successfully settled transactions (PROCESSED files only) | | #Advices | Count of advices (typically 0) | | #Records | Count of detail records in the input file (PROCESSED files only; 0 in RECEIVED files) | ### 1.4.2 Detailed Response Files ABA outbound payment files do not generate a Detailed Response File. To identify which specific transactions failed and view error details, check the Azupay Dashboard under Transactions > Payments. Each transaction from the file will appear with its status (SETTLED or FAILED) and any associated error messages. ## 1.5 Timing Expectations ### 1.5.1 Polling and Pickup Files are polled every 1 minute. After you upload a file, it will be picked up within the next polling cycle (maximum 1 minute wait). ### 1.5.2 RECEIVED Response File The RECEIVED Summary Response File appears within 0 to 120 seconds of file pickup. ### 1.5.3 PROCESSED Response File The PROCESSED Summary Response File timing varies based on the number of transactions in the file. There is no fixed SLA for processing time. Monitor the Dashboard under Transactions > Payments to see transaction statuses as they are processed. ### 1.5.4 Archiving File archiving (move to `archive/` subdirectory with `.processed.` or `-error.` filename change) occurs after the RECEIVED response file is generated, once processing completes or validation fails. ## 1.6 Error Handling ### 1.6.1 File Rejection Errors File rejection errors prevent successful processing and result in: * A RECEIVED response file (confirming pickup) * A REJECTED response file (with error details) * **No PROCESSED response file** * The original file moved to `archive/` with `-error.` in the filename **Common causes:** * Invalid ABA format (wrong record types, incorrect field positions, malformed records) * File corruption or encoding issues (non-ASCII characters, truncated lines) * Empty files or files with no detail records * Trailer control totals that do not match detail record totals * Trailer record count that does not match the number of type 1 records * File decryption failures (for encrypted files) * Complete file parsing failures (when all rows contain errors and no transactions can be processed) **Resolution:** * Review the REJECTED response file for specific error details * Correct the file format and resubmit * Ensure the file uses ASCII encoding * Verify trailer totals and record counts match the detail records * Check the Dashboard or contact support@azupay.com.au for additional assistance ### 1.6.2 Transaction-Level Errors Transaction-level errors do not prevent processing. The file reaches PROCESSED state, and individual transaction failures are reported in the PROCESSED Summary Response File as aggregate counts (`#Returned Payments` and `$Returned Payments`). **Common causes:** * Invalid or non-existent BSB * Invalid account number or closed account * Insufficient funds in the originating account * Payment amount outside allowed limits **Resolution:** * Check the Dashboard under Transactions > Payments to identify which transactions failed and view error messages * Correct the transaction details and resubmit in a new file * Contact the beneficiary to confirm account details if needed ### 1.6.3 Identifying Failed Transactions The PROCESSED Summary Response File shows only aggregate failure counts. To identify which specific transactions failed: 1. Navigate to the Azupay Dashboard: Transactions > Payments 2. Filter by the batch identifier or processing date 3. Review the status column for each transaction (SETTLED or FAILED) 4. Click on failed transactions to view error details and error codes ## 1.7 Support For assistance with file processing, response file interpretation, or error resolution, contact the Azupay Support Team at support@azupay.com.au. Include the following information: * Environment (UAT or Production) * Original filename and timestamp of submission * Connectivity model (Azupay Hosted SFTP Server or Customer Hosted SFTP Server) * Contents of RECEIVED, PROCESSED, and REJECTED response files (if generated) * Error messages or unexpected behaviour observed