NZ faster payments and A2A integration¶


ID	`MOD-122`
System	SD04
Repo	`bank-payments`
Build status	Deployed
Deployed	Yes
Last commit	`088500e`

Purpose¶

Provides NZ interbank payment capability via the Payments NZ clearing framework. Handles outbound Account2Account (A2A) credit transfers, inbound credit receipts, settlement batch participation, and return payment processing. Operates under the Payments NZ rules and through the bank's sponsor banking relationship (ADR-005). NZ only — AU interbank payments (NPP/Osko) are handled by MOD-120.

Jurisdiction: New Zealand only. Feature flag: payments.nz_interbank.enabled.

Compliance rationale¶

Payments NZ Rules (nz-payments-nz-rules) govern interbank credit transfers, including same-day settlement obligations, return payment handling, and participant conduct. PAY-002 (Settlement Risk Policy) requires that settlement exposure is monitored and that the bank participates in the Payments NZ settlement model via its sponsor bank. The Payments NZ Rules also impose obligations on banks to credit inbound payments promptly — typically within 2 hours of receipt during business hours.

Commercial rationale¶

NZ interbank transfers are the foundation of everyday banking. Customers need to send money to accounts at other NZ banks — to pay rent, pay tradespeople, pay family members. Without NZ interbank capability, the platform cannot serve as a primary bank account in New Zealand.

Payment types supported¶

Standard credit transfer (BSB-equivalent in NZ: bank code + branch code + account number + suffix)
Batch credit (multiple credits to different accounts in one submission — for SME payroll)
Same-day settlement (for payments submitted before the daily cut-off)

Data model¶

-- payments.nz_interbank_payments
CREATE TABLE payments.nz_interbank_payments (
  payment_id         UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  direction          TEXT NOT NULL CHECK (direction IN ('outbound','inbound')),
  account_id         UUID NOT NULL REFERENCES core.accounts(account_id),
  beneficiary_bank   TEXT NOT NULL,  -- NZ bank code
  beneficiary_branch TEXT NOT NULL,
  beneficiary_account TEXT NOT NULL,
  beneficiary_suffix TEXT,
  beneficiary_name   TEXT NOT NULL,
  amount             NUMERIC(18,2) NOT NULL,
  currency           TEXT NOT NULL DEFAULT 'NZD',
  particulars        TEXT,  -- NZ payment reference fields
  code               TEXT,
  reference          TEXT,
  payment_date       DATE NOT NULL,
  status             TEXT NOT NULL DEFAULT 'pending' CHECK (status IN ('pending','submitted','cleared','settled','returned','disputed')),
  clearing_reference TEXT,  -- Payments NZ clearing reference
  settlement_batch   TEXT,
  returned_at        TIMESTAMPTZ,
  return_reason_code TEXT,
  posting_id         UUID,
  created_at         TIMESTAMPTZ NOT NULL DEFAULT now()
);

Key operations¶

1. Outbound payment¶

Customer enters bank/branch/account/suffix in payment initiation (MOD-071). System validates format using the NZ account number validation algorithm. MOD-020 pre-payment validation runs → MOD-023 fraud score applied → debit posted via MOD-001 → submitted to sponsor bank API → clearing_reference recorded. Payments submitted before the daily cut-off (typically 3pm NZST) settle same day. Payments submitted after cut-off settle the next business day.

2. Inbound payment¶

Sponsor bank delivers an inbound credit notification. Module resolves the notification to the destination account. Credit posted via MOD-001. Customer notified via MOD-063 within 60 minutes of receipt during business hours, meeting the Payments NZ obligation for prompt crediting.

3. Returns¶

If an outbound payment returns (invalid account, account closed, beneficiary bank reject): credit posted back to the originating account via MOD-001, status set to returned, notification dispatched via MOD-063 with the return reason expressed in plain language.

4. Settlement reconciliation¶

Daily: MOD-081 reconciles the settlement batch against the sponsor bank's settlement statement. Any discrepancies are flagged to operations for investigation.

5. NZ account number format¶

NZ accounts use the format XX-XXXX-XXXXXXX-XX (bank-branch-account-suffix). This module validates format and performs the Payments NZ account number validation checksum before any submission to the clearing network.

Requirements¶

FR-553 through FR-556.

Module dependencies¶

Depends on¶

Module	Title	Required?	Contract	Reason
MOD-001	Double-entry posting engine	Required	—	Interbank payment debits and inbound credits are posted via the double-entry engine.
MOD-020	Pre-payment validation suite	Required	—	Pre-payment validation runs before every outbound NZ interbank submission.
MOD-023	Transaction fraud scorer	Required	—	Transaction fraud scorer screens all NZ interbank payments.
MOD-081	Payment reconciliation engine	Optional	—	NZ interbank settlement batches will be reconciled via MOD-081 in v2; v1 defers NZ_INTERBANK rail reconciliation (V1_MATCH_RAILS env var governs which rails MOD-081 processes).
MOD-063	Notification orchestration	Required	—	Payment confirmation, return, and alert notifications are dispatched via notification orchestration.
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 (payments.nz_interbank_payments).
MOD-104	AWS shared infrastructure bootstrap	Required	—	AWS shared infrastructure provisioned by MOD-104 (EventBridge buses, API Gateway, Lambda execution role) 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`	All outbound NZ interbank payments pass pre-payment validation (balance, sanctions, daily limits) before submission to the Payments NZ clearing network.
PAY-002	Settlement Risk Policy	`LOG`	Every NZ interbank payment instruction, clearing confirmation, and settlement batch entry is logged to the payment audit trail for settlement risk management purposes.
PAY-005	Payment Fraud Prevention Policy	`AUTO`	NZ interbank payments pass through the transaction fraud scorer before submission; high-risk payments trigger a review hold.
PAY-009	Payment Exceptions, Returns & Reversals Policy	`AUTO`	Returned payments (invalid account, account closed) are credited back to the originating account automatically with a customer notification.
REP-005	Data Quality & Assurance Policy	`LOG`	All interbank payment data is logged with Payments NZ clearing references for data quality and reconciliation purposes.

Capabilities satisfied¶

(No capabilities mapped)

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