PayID and Osko integration

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

---

Purpose

MOD-120 provides PayID registration and management, and Osko payment initiation and receipt via Australia's New Payments Platform (NPP). PayID allows customers to receive money using a proxy identifier — mobile number, email address, or ABN — instead of BSB and account number. Osko is the real-time overlay service that enables instant account-to-account transfers 24/7/365 with a 15-second clearing target.

Jurisdiction

Australia only. The module is inactive for NZ-jurisdiction accounts. Feature flag: payments.osko.enabled. Operates through the bank's sponsor banking relationship which provides NPP connectivity (ADR-005).

Compliance rationale

NPP Rules (au-npp-rules) govern PayID management — including portability, disputes, and cancellation — and Osko payment obligations. The AU ePayments Code applies to unauthorised Osko transactions and error correction. The Scam-Safe Accord (au-scam-safe-accord) imposes specific obligations around confirmation of payee: the name confirmation step in the outbound payment flow is a direct Scam-Safe Accord requirement. ASIC and AFCA have increasing supervisory focus on NPP fraud, particularly Authorised Push Payment (APP) scams. The friction and warning measures applied to high-value first-time payees are designed to reduce APP scam exposure.

Commercial rationale

PayID and Osko are expected features of any Australian bank account. Customers want to be findable via their phone number and to send money instantly. The inability to receive a PayID makes the bank invisible to NPP-sending institutions — senders see the recipient's bank as "not NPP-enabled" and may be prompted to use alternative transfer methods. Osko also underpins instant merchant settlement use cases planned for future product tiers.

Data model

-- payments.payid_registrations
CREATE TABLE payments.payid_registrations (
  payid_id           UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  account_id         UUID NOT NULL REFERENCES core.accounts(account_id),
  payid_type         TEXT NOT NULL CHECK (payid_type IN ('mobile','email','abn','organisation_id')),
  payid_value        TEXT NOT NULL,
  display_name       TEXT NOT NULL,  -- shown to senders
  status             TEXT NOT NULL DEFAULT 'active' CHECK (status IN ('active','suspended','deregistered')),
  registered_at      TIMESTAMPTZ NOT NULL,
  deregistered_at    TIMESTAMPTZ,
  ported_from_bsb    TEXT,  -- if ported from another bank
  created_at         TIMESTAMPTZ NOT NULL DEFAULT now(),
  UNIQUE (payid_type, payid_value)
);

-- payments.osko_payments
CREATE TABLE payments.osko_payments (
  osko_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),
  payid_used         TEXT,  -- null if BSB/account used directly
  payid_type         TEXT,
  resolved_bsb       TEXT,
  resolved_account   TEXT,
  beneficiary_name   TEXT NOT NULL,
  amount             NUMERIC(18,2) NOT NULL,
  currency           TEXT NOT NULL DEFAULT 'AUD',
  description        TEXT,
  end_to_end_id      TEXT NOT NULL UNIQUE,
  npp_message_id     TEXT,
  status             TEXT NOT NULL DEFAULT 'pending' CHECK (status IN ('pending','processing','completed','returned','disputed')),
  submitted_at       TIMESTAMPTZ,
  completed_at       TIMESTAMPTZ,
  returned_at        TIMESTAMPTZ,
  return_reason      TEXT,
  posting_id         UUID,
  name_confirmed     BOOLEAN NOT NULL DEFAULT false,
  name_confirmed_at  TIMESTAMPTZ,
  created_at         TIMESTAMPTZ NOT NULL DEFAULT now()
);

PayID lifecycle

Registration at account opening

When a customer opens PRD-001 (everyday account), they are prompted to register their mobile number and/or email address as a PayID. Default behaviour is opt-in. Registrations are stored in payid_registrations and provisioned to the NPP directory via the sponsor bank API.

PayID management

Customers can add a new PayID, update the display name shown to senders, suspend a PayID temporarily, or deregister via MOD-072 (customer profile and settings). Deregistration is immediate — the PayID is no longer resolvable within 2 minutes of the instruction, per NPP Rule 4.7.

PayID portability

When a customer migrating from another institution wants to bring an existing PayID: the module initiates a port request via the sponsor bank. The current PayID holder at the source institution has 5 business days to raise a dispute. If no dispute is lodged, the port completes and ported_from_bsb records the source institution's BSB.

Osko payment send flow

1. Customer enters a PayID value — or BSB and account number — in MOD-071 (payment initiation).
2. The module resolves the PayID to account details via the NPP directory in real time, with a 2-second SLA. The beneficiary display name is returned.
3. Name confirmation — the resolved display name is shown to the customer: "You are paying [Display Name]." The customer must explicitly confirm. name_confirmed = true is set before any funds are committed or any network submission is made. This step is not skippable. It is a Scam-Safe Accord requirement.
4. MOD-020 pre-payment validation → MOD-023 fraud score. Enhanced fraud rules apply to Osko: if the recipient has not previously been paid by this customer and the amount exceeds $1,000, additional friction is applied — a 5-second countdown with a scam awareness warning before the confirm button activates.
5. Post debit via MOD-001 → submit NPP message via sponsor bank → record npp_message_id and set status to processing.
6. Completion notification dispatched via MOD-063 within 30 seconds of submission.

Inbound Osko receipt

1. Sponsor bank delivers an inbound NPP credit notification to the module.
2. The module resolves the destination account via PayID lookup or direct BSB/account match.
3. Credit posted via MOD-001 immediately.
4. Push notification dispatched via MOD-063 within 5 seconds: "[Sender name] sent you $[amount]".

Returns handling

If an outbound Osko payment is returned (account closed, PayID deregistered between lookup and settlement, scheme rejection):

1. Credit account via MOD-001.
2. Set status to returned and record return_reason.
3. Notify customer via MOD-063 with return reason expressed in plain English. NPP scheme return reason codes are mapped to a customer-facing message catalogue.

Scam-Safe Accord obligations

The module implements the following specific obligations from the Scam-Safe Accord:

• Name confirmation — mandatory payee name display and acknowledgement before every outbound Osko payment (implemented in the send flow above).
• High-value first-time payee friction — delay and scam warning for transfers above $1,000 to a new payee.
• In-app scam reporting — a "Report a scam" action is available on every Osko transaction detail screen; this routes to MOD-053 (case management) with case type scam_report.
• Onboarding education — scam awareness content is shown to the customer during their first session with the Osko payment flow, before they submit their first payment.

Requirements satisfied

FR-541 — PayID registration and management, including portability. FR-542 — Osko payment initiation with name confirmation and fraud friction. FR-543 — Inbound Osko receipt and real-time credit posting. FR-544 — Osko returns processing and Scam-Safe Accord obligations.

---

Module dependencies

Depends on

Module	Title	Required?	Contract	Reason
MOD-001	Double-entry posting engine	Required	—	Osko debits and inbound credits are posted via the double-entry engine in real time.
MOD-003	Real-time balance engine	Required	—	Real-time balance check is required before every Osko payment submission — Osko is irrevocable once submitted.
MOD-020	Pre-payment validation suite	Required	—	Pre-payment validation must clear before Osko submission.
MOD-023	Transaction fraud scorer	Required	—	Transaction fraud scorer applies enhanced rules to Osko payments given their immediate and irrevocable nature.
MOD-063	Notification orchestration	Required	—	Inbound Osko receipt notifications are dispatched immediately via notification orchestration.

Required by

Module	Title	As	Contract
MOD-144	Confirmation of payee — account name verification	Optional enhancement	—

---

Policies satisfied

Policy	Title	Mode	How
PAY-001	Payment Operations Policy	GATE	PayID-addressed payments are validated for PayID existence and account reachability before funds are committed.
PAY-005	Payment Fraud Prevention Policy	AUTO	All Osko payment initiations pass through the transaction fraud scorer with additional real-time rules for new-payee high-value transfers.
PAY-009	Payment Exceptions, Returns & Reversals Policy	AUTO	Osko payment returns (to wrong PayID, account closed) are processed automatically with immediate customer notification and funds reversal.
CON-005	Fee & Pricing Transparency Policy	AUTO	The resolved account holder name is displayed to the customer before confirming an Osko payment — confirmation of payee name is mandatory.
AML-005	Transaction Monitoring Policy	LOG	All real-time Osko payments are logged with full transaction metadata for transaction monitoring purposes.

---

Capabilities satisfied

(No capabilities mapped)

---

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