ATM network integration¶


ID	`MOD-123`
System	SD04
Repo	`bank-payments`
Build status	Not started
Deployed	No

Purpose¶

Handles real-time ATM withdrawal authorisation, ATM transaction posting, and ATM network settlement reconciliation. Processes inbound authorisation requests from the card network (via the sponsor bank's ATM network connectivity), validates them against balance and card controls, and responds within the network's required response time (typically under 1 second). NZ: connects to shared ATM networks (Westpac/BNZ/ANZ sharing arrangements under the Payments NZ framework). AU: connects to the rediATM network and major bank surcharge-free agreements.

Prerequisite: Physical card issuance (MOD-124) must be operational. ATM transactions require a physical card with a valid PAN enrolled in the network.

Compliance rationale¶

The ePayments Code (AU) and Banking Code obligations require banks to respond promptly to disputed ATM transactions and to correctly attribute liability for card-not-present vs. card-present fraud. PCI DSS (PAY-006) governs how card data is handled during authorisation — the platform must use point-to-point encryption and must never log or store full PANs in application logs.

Data model¶

-- payments.atm_authorisations
CREATE TABLE payments.atm_authorisations (
  auth_id            UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  card_id            UUID NOT NULL,
  account_id         UUID NOT NULL REFERENCES core.accounts(account_id),
  atm_id             TEXT NOT NULL,  -- terminal ID from network message
  atm_location       TEXT,
  network            TEXT NOT NULL,  -- 'nz_eftpos','visa','mastercard','redi'
  amount             NUMERIC(18,2) NOT NULL,
  currency           TEXT NOT NULL,
  request_received_at TIMESTAMPTZ NOT NULL,
  decision           TEXT NOT NULL CHECK (decision IN ('approved','declined','reversed')),
  decline_reason     TEXT,
  response_sent_at   TIMESTAMPTZ,
  response_time_ms   INT,  -- for SLA monitoring
  posting_id         UUID,
  fraud_score        NUMERIC(5,2),
  created_at         TIMESTAMPTZ NOT NULL DEFAULT now()
);

-- payments.atm_settlements
CREATE TABLE payments.atm_settlements (
  settlement_id      UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  settlement_date    DATE NOT NULL,
  network            TEXT NOT NULL,
  batch_reference    TEXT NOT NULL,
  total_debits       NUMERIC(18,2) NOT NULL,
  total_credits      NUMERIC(18,2) NOT NULL,
  reconciled         BOOLEAN NOT NULL DEFAULT false,
  reconciled_at      TIMESTAMPTZ,
  created_at         TIMESTAMPTZ NOT NULL DEFAULT now()
);

Key operations¶

1. Authorisation flow¶

An inbound ATM request arrives via the sponsor bank's network interface. The module looks up the card → account → available balance (MOD-003). Checks performed: ATM toggle enabled (MOD-078), daily ATM limit not exceeded (MOD-021), fraud score acceptable (MOD-023). An approved or declined response is returned within an 800ms SLA. If approved, a pre-authorisation hold (pre-auth debit) is posted via MOD-001 immediately to reduce available balance; the hold is finalised on settlement.

2. Reversal¶

If an ATM dispenses no cash but an authorisation was approved (dispense failure): an inbound reversal message triggers release of the hold via MOD-001. The customer is notified via MOD-063 if the reversal occurs unexpectedly.

3. Settlement¶

Daily: the sponsor bank delivers an ATM settlement file. MOD-081 reconciles posted ATM transactions against the settlement file. Discrepancies are flagged to operations for investigation.

4. Surcharge disclosure¶

The app displays surcharge-free ATM networks in the card section (MOD-078 UI). Customers can locate surcharge-free ATMs in-app before making a withdrawal.

Requirements¶

FR-557 through FR-560.

Module dependencies¶

Depends on¶

Module	Title	Required?	Contract	Reason
MOD-001	Double-entry posting engine	Required	—	ATM withdrawal postings and reversals are executed via the double-entry engine.
MOD-003	Real-time balance engine	Required	—	Real-time available balance check is required before every ATM authorisation response.
MOD-023	Transaction fraud scorer	Required	—	ATM transaction fraud scoring uses device and location signals to identify card-present fraud.
MOD-078	Card & account controls	Required	—	Card controls (ATM toggle, daily limit) are enforced at the point of authorisation using the settings managed by the card controls module.
MOD-124	Physical card issuance and bureau integration	Required	—	Physical card issuance (MOD-124) is a prerequisite — ATM transactions require a physical card with a valid PAN and PIN.

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`	ATM withdrawal requests are validated in real time against the customer's available balance and daily ATM limit before authorisation is returned to the network.
PAY-005	Payment Fraud Prevention Policy	`AUTO`	ATM withdrawal requests are screened by the transaction fraud scorer using device and location signals; anomalous requests trigger a decline or step-up challenge.
PAY-002	Settlement Risk Policy	`LOG`	All ATM authorisation decisions, reversals, and settlement entries are logged to the payment audit trail.
CON-005	Fee & Pricing Transparency Policy	`AUTO`	Surcharge-free network membership details are disclosed to the customer in the app so they know which ATMs can be used without fees.

Capabilities satisfied¶

(No capabilities mapped)

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