Direct debit mandate management

ID	MOD-114
System	SD04
Repo	bank-payments
Build status	Deployed
Deployed	Yes
Last commit	63b867eeda3a9171bef287189cb6b36afede3a4a

---

What it does

MOD-114 manages the mandate registry and processing pipeline for direct debits in both NZ and AU. The module is a thin integration layer — the actual payment rail (NZ Payments NZ DDR scheme; AU BECS via sponsor bank) is operated by an external provider. MOD-114 owns: mandate storage, mandate validation at debit presentation time, dishonour processing, customer-initiated cancellation, and the dispute workflow for unauthorised debits.

External rail integration

NZ DDR (Direct Debit Register) is administered by Payments NZ; AU BECS is administered by AusPayNet via a sponsor/correspondent bank. The bank connects to these rails via API (not direct scheme membership at launch). The integration partner handles scheme connectivity; MOD-114 provides the mandate validation and ledger instruction layer.

Mandate lifecycle

Creation: Customer authorises a biller mandate via the bank's app (pre-approval flow) or a biller-initiated paper/electronic authorisation processed by the bank. Mandate is stored with: biller name, biller ID, account number, maximum amount per debit (if customer-specified), frequency, effective date, expiry date (if applicable).

Validation at presentation: When a debit file is received from the external provider, each debit entry is validated: mandate exists and is active, biller ID matches, amount does not exceed the mandate maximum (if set), account is in Active state (MOD-007). Debits failing validation are returned with the appropriate scheme return code.

Dishonour: If the account has insufficient funds or is blocked, the debit is returned with a dishonour code. A dishonour fee is assessed via MOD-110 (if configured in tenant fee schedule). The customer is notified via MOD-063 with the biller name and dishonour reason.

Cancellation: Customer can cancel any mandate instantly via the app — effective immediately; any debit presentation received after cancellation is returned regardless of timing. Cancellation is logged and the external provider is notified.

Dispute: Customer can dispute a direct debit within 12 months of the debit date (NZ/AU consumer protection periods). Dispute triggers MOD-053 (case and complaint management) and places a query hold on repeat debits from the same biller pending investigation.

Data model

-- payments.direct_debit_mandates (Postgres)
CREATE TABLE payments.direct_debit_mandates (
  mandate_id   uuid PRIMARY KEY DEFAULT gen_random_uuid(),
  party_id     uuid NOT NULL,
  account_id   uuid NOT NULL,
  jurisdiction text NOT NULL CHECK (jurisdiction IN ('NZ','AU')),
  biller_id    text NOT NULL,
  biller_name  text NOT NULL,
  scheme_ref   text,               -- DDR ref (NZ) or APCA ID (AU)
  max_amount   numeric(18,2),      -- null = no customer-set maximum
  frequency    text,               -- WEEKLY | FORTNIGHTLY | MONTHLY | VARIABLE
  status       text NOT NULL CHECK (status IN ('ACTIVE','CANCELLED','SUSPENDED','EXPIRED')),
  created_at   timestamptz NOT NULL DEFAULT now(),
  cancelled_at timestamptz,
  cancel_reason text
);

---

Module dependencies

Depends on

Module	Title	Required?	Contract	Reason
MOD-001	Double-entry posting engine	Required	—	Direct debit postings are executed as ledger entries through the posting engine once mandate validation passes.
MOD-020	Pre-payment validation suite	Required	—	Pre-payment validation (balance, account state, sanctions) runs before every direct debit posting.
MOD-110	Fee engine	Required	—	Dishonour fees on failed direct debit presentations are assessed through the fee engine.
MOD-104	AWS shared infrastructure bootstrap	Required	—	AWS shared infrastructure required before this module can be deployed.
MOD-053	Case & complaint management module	Required	—	Dispute workflow (FR-509) creates a case and places a query hold via MOD-053 POST /internal/cases — synchronous HTTP invoke required to meet the 60-second case-creation SLA.
MOD-063	Notification orchestration	Required	—	Dishonour (FR-508) and dispute (FR-509) customer notifications are delivered via MOD-063 consuming bank.payments.direct_debit_* events — notification SLA depends on MOD-063 availability.
MOD-157	External provider stub service	Required	—	External provider sponsor URLs for NZ DDR (clearing/ddr/base-url) and AU BECS (clearing/becs/base-url) are published by the provider stub and read at deploy time.
MOD-103	Neon database platform bootstrap	Required	—	Neon database must exist before this module can read or write Postgres.

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	A direct debit is only processed against an account if a valid active mandate exists for the requesting biller — no mandate, no debit.
PAY-002	Settlement Risk Policy	LOG	All mandate lifecycle events and debit presentations are logged immutably in payments.direct_debit_events, providing the settlement risk and scheme-rule audit trail required by NZ Payments NZ DDR and AU BECS.
PRI-001	Privacy Policy	GATE	Mandate data (biller name, account reference) is stored and accessible only to the account holder and authorised bank staff — not shared with third parties beyond the payment rail.

---

Capabilities satisfied

(No capabilities mapped)

---

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