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<separator1><numeric-id><separator2><suffix>.aba

Where:

• <separator1> and <separator2> can each be either a hyphen (-) or underscore (_)
• <numeric-id> contains only digits (0-9)
• <suffix> can contain any characters

Components:

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 [email protected] 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: <filename>_RECEIVED.txt where <filename> 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: <filename>_PROCESSED.txt where <filename> 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: <filename>_REJECTED.txt where <filename> 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

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 [email protected] 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 [email protected]. 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