BPAY payment integration

ID	MOD-119
System	SD04
Repo	bank-payments
Build status	Deployed
Deployed	Yes
Last commit	178e49975435ec5926a3b4f612f5d9ee9efc8495

---

Purpose

MOD-119 provides BPAY payment capability for Australian customers. BPAY is the primary bill payment infrastructure in Australia, used to pay utilities, insurance, council rates, tax obligations, and other registered billers. The module handles BPAY payment initiation (payer side), biller directory lookup, settlement batch participation, and returns processing. It operates as a participant in the BPAY scheme via the bank's sponsor banking relationship (ADR-005).

Jurisdiction

Australia only. The module is inactive for NZ-jurisdiction accounts. Feature flag: payments.bpay.enabled — set at the tenant level.

Compliance rationale

The AU ePayments Code governs BPAY transactions, particularly around liability for mistaken payments, unauthorised transactions, and processing error remediation. The BPAY scheme rules (operated by BPAY Pty Ltd) impose obligations on participant banks regarding settlement times, dishonour handling, and dispute resolution timelines. PAY-009 (Payment Exceptions, Returns & Reversals Policy) applies directly to BPAY dishonour and return events.

Commercial rationale

BPAY is a table-stakes capability for any Australian retail bank. Customers use BPAY to pay bills from within their banking app — inability to make BPAY payments renders an account unsuitable as a primary bank account. Without BPAY, every prospective AU customer would need to maintain a separate bill payment arrangement, which is a UX regression and a material competitive disadvantage.

Data model

-- payments.bpay_payments
CREATE TABLE payments.bpay_payments (
  bpay_payment_id    UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  account_id         UUID NOT NULL REFERENCES core.accounts(account_id),
  biller_code        TEXT NOT NULL,
  biller_name        TEXT,  -- resolved from biller directory
  customer_reference TEXT NOT NULL,
  amount             NUMERIC(18,2) NOT NULL,
  currency           TEXT NOT NULL DEFAULT 'AUD',
  payment_date       DATE NOT NULL,  -- value date
  status             TEXT NOT NULL DEFAULT 'pending' CHECK (status IN ('pending','submitted','settled','returned','disputed')),
  batch_id           TEXT,  -- BPAY settlement batch reference
  sponsor_reference  TEXT,  -- sponsor bank submission reference
  returned_at        TIMESTAMPTZ,
  return_reason_code TEXT,
  posting_id         UUID,  -- reference to MOD-001 entry
  created_at         TIMESTAMPTZ NOT NULL DEFAULT now()
);

-- payments.bpay_biller_cache
CREATE TABLE payments.bpay_biller_cache (
  biller_code        TEXT PRIMARY KEY,
  biller_name        TEXT NOT NULL,
  accepted_amounts   TEXT NOT NULL CHECK (accepted_amounts IN ('fixed','variable','range')),
  min_amount         NUMERIC(18,2),
  max_amount         NUMERIC(18,2),
  crn_format         TEXT,  -- regex for CRN validation
  last_refreshed     TIMESTAMPTZ NOT NULL
);

Key operations

1. Biller lookup

Customer enters a biller code in the app. The module queries bpay_biller_cache, which is refreshed daily from the BPAY biller directory API via the sponsor bank. The response returns the biller name and CRN format for client-side validation. If the biller code is not present in cache, a real-time lookup is made via the sponsor bank API with a 5-second timeout; failure results in an inline error prompting the customer to retry.

2. CRN validation

The customer reference number is validated against the biller's published CRN format — either a Luhn check or a regex pattern as specified by the biller record. An invalid CRN blocks submission with an inline error before any funds are committed or any network call is made to the scheme.

3. Payment submission

On customer confirmation:

1. MOD-020 pre-flight checks — balance, sanctions screening, daily payment limits.
2. MOD-023 fraud score — BPAY-specific rules applied.
3. Debit account via MOD-001 (double-entry).
4. Submit to sponsor bank BPAY API; record sponsor_reference and set status to submitted.

Payments submitted before the configured cut-off (default: 17:00 AEST) are processed same-day. Payments submitted after cut-off are queued for the next business day. The cut-off time is configurable at the tenant level.

4. Settlement

The sponsor bank confirms settlement batch inclusion. The module updates status to settled and records the batch_id. MOD-081 reconciles the batch against the sponsor bank settlement statement.

5. Returns and dishonours

Returned payments received from the sponsor bank (e.g. invalid biller code, biller rejection, account closed at biller side) trigger the following:

1. Credit account via MOD-001.
2. Set status to returned and record return_reason_code.
3. Dispatch notification via MOD-063 with the return reason expressed in plain language (raw scheme reason codes are mapped to a customer-facing message catalogue).

6. Dispute handling

When a customer disputes a BPAY payment (wrong biller, wrong amount, not authorised), a case is created in MOD-053 (case management) with case type bpay_dispute. The dispute is submitted to the sponsor bank via the BPAY dispute process. The scheme allows a 90-day dispute window from the payment date.

7. Transaction history

BPAY transactions surface in MOD-070 (transaction history) enriched with biller name (resolved from biller directory, not raw biller code), amount, payment date, and CRN. A status badge indicates Pending, Settled, or Returned.

UX requirements

The BPAY payment flow in MOD-071 (payment initiation) must implement:

• Biller code entry with real-time biller name resolution.
• CRN entry with format mask derived from biller CRN format.
• Amount entry, or pre-populated fixed amount where biller data specifies a fixed amount.
• Scheduled date picker — pay now or select a future date.
• Review screen showing biller name, CRN, amount, and value date before confirmation.
• Confirm step with biometric gate (same as standard payment flow).
• Recent billers list for quick re-access — stored per customer, shown on the BPAY entry screen.

Requirements satisfied

FR-537 — Biller lookup and CRN validation. FR-538 — BPAY payment submission and cut-off handling. FR-539 — Settlement batch participation and reconciliation. FR-540 — Returns and dishonour processing.

---

Module dependencies

Depends on

Module	Title	Required?	Contract	Reason
MOD-001	Double-entry posting engine	Required	—	BPAY debits and credits are posted as ledger entries via the double-entry engine.
MOD-020	Pre-payment validation suite	Required	—	Pre-payment validation must run before each BPAY submission — balance check, sanctions, fraud pre-screen.
MOD-023	Transaction fraud scorer	Required	—	Transaction fraud scorer screens BPAY payments for anomalous patterns before submission.
MOD-081	Payment reconciliation engine	Required	—	BPAY settlement batches are reconciled via the payment reconciliation engine.
MOD-063	Notification orchestration	Required	—	Payment confirmations, dishonour notifications, and BPAY-specific alerts are dispatched via notification orchestration.

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	BPAY payments are validated against biller code, customer reference number format, and payment amount limits before submission to the BPAY scheme.
PAY-005	Payment Fraud Prevention Policy	AUTO	BPAY transactions are passed through the transaction fraud scorer before submission; high-risk transactions are held for review.
PAY-009	Payment Exceptions, Returns & Reversals Policy	AUTO	BPAY dishonours and returns are handled automatically — funds are credited back to the customer's account and a notification is dispatched.
CON-005	Fee & Pricing Transparency Policy	AUTO	BPAY biller name and reference are displayed in transaction history with full detail — no generic merchant string.
REP-005	Data Quality & Assurance Policy	LOG	All BPAY transactions are logged with biller code, customer reference, and settlement batch reference 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-119.yaml