Agency banking adapter¶


ID	`MOD-137`
System	SD04
Repo	`bank-payments`
Build status	Deployed
Deployed	Yes
Last commit	`602d30c`

Purpose¶

Agency banking allows customers to perform basic cash transactions — deposits, withdrawals, and balance enquiries — at a third-party service point rather than at a branch or ATM. MOD-137 provides the adapter that ingests the daily transaction batch file delivered by the agency network, validates each item, posts it to the customer's account, and reconciles the batch against the agency network's settlement file.

Scope¶

Australia — primary integration is with Australia Post's agency banking service. Australia Post operates an extensive outlet network and is the dominant agency banking channel for Australian financial institutions. Integration is file-based: Australia Post delivers an encrypted SFTP file each business day containing all transactions processed across the agency network for this institution's customers.

New Zealand — configurable. NZ Post historically provided agency banking for NZ financial institutions but usage is significantly lower. The module supports NZ Post as an alternative agency network via the same file-based adapter; the agency_network field on the batch record determines which network's file format and settlement process applies. Additional agency network adapters (beyond Australia Post and NZ Post) can be configured via the other network type.

Agency banking is particularly important for customers in regional areas with limited branch coverage and for older demographic segments who prefer in-person cash transactions. It complements the digital channel rather than substituting for it.

Agency network integration model¶

Integration is file-based, not real-time. The agency terminal at the outlet does not communicate directly with the bank's platform during the transaction. The teller or terminal accepts the transaction, and the agency network collects all transactions across its outlets during the business day. At end of day, the network delivers a single encrypted batch file to the bank via SFTP.

Consequences of this model:

The customer's account balance is not updated at the point of the in-outlet transaction. Balance updates occur when the batch file is processed, typically within a few hours of end of business day.
A customer presenting at a second outlet on the same day may see a balance that does not reflect an earlier same-day agency transaction.
Withdrawal validation uses the end-of-prior-business-day available balance at the time of the agency terminal transaction; overdrafts that result from same-day intraday movements before the batch is processed are handled via the standard overdraft reconciliation process.

File format¶

The Australia Post agency banking file is a standard delimited format delivered as an encrypted file via SFTP. Each record contains:

Field	Description
`transaction_type`	`deposit`, `withdrawal`, or `balance_enquiry`
`account_number`	Customer account number as entered at the terminal
`bsb`	BSB of the nominated account
`amount`	Transaction amount in AUD (zero for balance enquiries)
`timestamp`	Date and time of the transaction at the outlet terminal
`terminal_id`	Unique identifier of the outlet terminal
`agent_outlet_code`	Australia Post outlet code

NZ Post file format follows the equivalent NZ agency banking specification. The agency_network value on the batch record drives format selection at parse time.

Data model¶

-- Agency batch files received from the network
CREATE TABLE payments.agency_batch_files (
    batch_id             UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    agency_network       TEXT NOT NULL CHECK (agency_network IN (
                             'australia_post', 'nz_post', 'other'
                         )),
    file_reference       TEXT NOT NULL UNIQUE,   -- network-assigned file identifier
    transaction_date     DATE NOT NULL,
    item_count           INT NOT NULL,
    total_deposits       NUMERIC(18,2) NOT NULL DEFAULT 0,
    total_withdrawals    NUMERIC(18,2) NOT NULL DEFAULT 0,
    status               TEXT NOT NULL DEFAULT 'received' CHECK (status IN (
                             'received',
                             'processing',
                             'settled',
                             'reconciled',
                             'exceptions'
                         )),
    received_at          TIMESTAMPTZ NOT NULL DEFAULT now()
);

-- Individual transactions from agency batch files
CREATE TABLE payments.agency_transactions (
    agency_tx_id         UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    batch_id             UUID NOT NULL REFERENCES payments.agency_batch_files(batch_id),
    account_id           UUID REFERENCES core.accounts(account_id),  -- null if unmatched
    account_number_raw   TEXT NOT NULL,          -- as received in file, before matching
    transaction_type     TEXT NOT NULL CHECK (transaction_type IN (
                             'deposit', 'withdrawal', 'balance_enquiry'
                         )),
    amount               NUMERIC(18,2) NOT NULL DEFAULT 0,
    terminal_id          TEXT NOT NULL,
    agent_outlet_code    TEXT NOT NULL,
    status               TEXT NOT NULL DEFAULT 'matched' CHECK (status IN (
                             'matched',
                             'posted',
                             'quarantined',
                             'unmatched'
                         )),
    posting_id           UUID,                   -- reference to MOD-001 ledger entry
    failure_reason       TEXT,
    created_at           TIMESTAMPTZ NOT NULL DEFAULT now()
);

CREATE INDEX ON payments.agency_transactions (batch_id);
CREATE INDEX ON payments.agency_transactions (account_id);
CREATE INDEX ON payments.agency_transactions (status);

account_id is nullable: it is populated after account matching succeeds. Items that cannot be matched to an account are set to unmatched and escalated to the operations queue. terminal_id and agent_outlet_code are carried through to the ledger transaction as location metadata; these fields are required for AML cash transaction reporting (see FR-611).

Key operations¶

File receipt and validation. The batch file is received via SFTP, decrypted, and parsed. Basic structural validation (record count, file totals, format compliance) is run before individual items are processed. A payments.agency_batch_files record is created with status received.

Account matching. Each transaction item is matched to a live account in the platform by account_number_raw and BSB. Successfully matched items have account_id populated and status set to matched. Items that cannot be matched are set to unmatched with a structured failure reason and added to the operations queue within 2 hours.

Validation gate. For each matched item: account status is checked (the account must be active); for withdrawals, available balance is checked via MOD-003. Items failing either check are quarantined with the failure reason (account_inactive, insufficient_funds, etc.) and reported to the operations queue.

AML threshold check. Items where transaction_type is deposit or withdrawal and amount is at or above the jurisdiction threshold (AUD 10,000 / NZD 10,000) are flagged for cash transaction reporting via the AML monitoring platform. The flag is set before posting; it does not delay or block the posting (see FR-611).

Posting. Valid items are posted via MOD-001: deposits as credits, withdrawals as debits. The posting_id is written to agency_transactions and status advances to posted. Balance enquiry items do not result in a posting and are marked posted after a response is logged.

Customer notification. For each item posted to an account, a transaction notification is dispatched via MOD-063 within 60 minutes of the posting completing. The notification includes the transaction type, amount, and agency outlet reference.

Settlement reconciliation. After the batch is fully processed, MOD-081 reconciles the processed item count and totals against the agency network's settlement file. Discrepancies are flagged to the operations queue within 2 hours. Unresolved discrepancies are escalated to the agency network within 1 business day (see FR-612).

Exception handling. Quarantined and unmatched items are surfaced in the operations queue with the failure reason, the raw account number, and the outlet reference. The operations team can manually match unmatched items, override quarantine with justification, or initiate a return to the agency network. All manual interventions are logged.

Requirements¶

FR-609 — System shall process incoming agency batch files by parsing each transaction, matching the account number to a live account in the platform, and validating the account status and available balance (for withdrawals) before posting; items that cannot be matched to an account, or where the account fails validation, must be quarantined with a structured failure reason and reported to the operations queue within 2 hours of the batch being received.

FR-610 — System shall post each valid agency deposit as a credit and each valid agency withdrawal as a debit via MOD-001 on the transaction date indicated in the batch file, and must dispatch a transaction notification to the customer via MOD-063 within 60 minutes of the posting for each agency transaction.

FR-611 — System shall detect agency cash transactions at or above the jurisdiction-specific AML reporting threshold in the batch file and must flag these items for cash transaction reporting via the AML monitoring platform, recording the terminal_id and agent_outlet_code as location metadata on the transaction — the AML flag must not delay the posting of the transaction.

FR-612 — System shall reconcile each processed agency batch against the agency network's settlement file via MOD-081, comparing item counts and total amounts per transaction type; any discrepancy must be flagged to the operations queue within 2 hours of reconciliation completing; unresolved discrepancies must be escalated to the agency network within 1 business day.

Module dependencies¶

Depends on¶

Module	Title	Required?	Contract	Reason
MOD-001	Double-entry posting engine	Required	—	Agency deposits and withdrawals are posted via the double-entry engine.
MOD-003	Real-time balance engine	Required	—	Available balance is checked per withdrawal item before posting.
MOD-081	Payment reconciliation engine	Optional	—	FR-612 batch reconciliation is owned by MOD-137 in v1. MOD-081 adds AGENCY to V1_MATCH_RAILS in v2.
MOD-063	Notification orchestration	Required	—	Per-transaction notifications (FR-610) dispatched via bank.payments.agency_ events; MOD-063 catch-all rule on bank.payments. covers all five new event types.
MOD-103	Neon database platform bootstrap	Required	—	Neon database and schema provisioned by MOD-103 must exist before this module can read or write Postgres.
MOD-104	AWS shared infrastructure bootstrap	Required	—	AWS shared infrastructure provisioned by MOD-104 (IAM role, EventBridge bus, SNS, KMS, S3) is required before this module can be deployed.

Required by¶

(No modules in this wiki currently declare a dependency on this module.)

Policies satisfied¶

Policy	Title	Mode	How
PAY-001	Payment Operations Policy	`GATE`	Each agency transaction in the batch file is validated against account status and available balance before posting; items that fail validation are quarantined with a structured failure reason.
AML-005	Transaction Monitoring Policy	`AUTO`	Agency cash transactions at or above the AML reporting threshold (AUD/NZD 10,000) are flagged for cash transaction reporting; the agency batch file includes transaction amounts enabling threshold detection.
CON-001	Customer Fairness & Conduct Policy	`AUTO`	Agency transactions are reflected in the customer's account balance and transaction history with the same speed as digital channel transactions — no delayed posting for the agency channel.
PAY-002	Settlement Risk Policy	`LOG`	All agency batch files, individual items, and reconciliation outcomes are logged to the payment audit trail.

Capabilities satisfied¶

(No capabilities mapped)

Part of SD04 — Payments Processing Platform Compiled 2026-05-22 from source/entities/modules/MOD-137.yaml