Integrated Payments – UX Specification

Related Technical Authority: Integrated Payments – Technical Specification

1. Purpose

This UX specification governs the staff and patient-facing experience of Integrated Payments — the platform-native payments layer embedded inside Primoro. It defines how staff initiate, manage, and audit payments across in-practice, online, and remote surfaces, and how patients pay outstanding balances and receive receipts. The primary roles it serves are front-of-house and clinical staff (payment initiation, refunds, reconciliation), practice managers and compliance officers (audit, approvals, exception handling), and patients (self-serve payment and receipt history).

2. Core UX Principles (Non-Negotiable)

These principles take precedence over visual preferences. If a design choice conflicts with a principle below, the principle wins.

• Action-first — users see the action they need next, not abstract status displays
• Governance always visible — when AI is involved, users always know what AI did and what they're confirming
• No dead toggles — every UI control either does something or doesn't appear
• Calm by default — the interface gets out of the way; alerts are reserved for things that genuinely need attention
• Progressive disclosure — advanced detail is one click away, not always-on
• Money is irreversible — any action that moves, refunds, or voids funds requires a deliberate confirmation step; destructive payment actions are never a single tap. Inferred from the technical spec's mandatory reason codes, optional approval workflows, and the requirement that irreversible state transitions be auditable (§3.2, §4.4).
• Compliance is always present, never intrusive — the audit trail, actor attribution, and approval state are accessible from every payment record but are not foregrounded unless the user is in a compliance or admin role. Inferred from §8 and §9 audit and access control requirements.
• No silent failures — every failed payment, failed PMS writeback, or failed receipt delivery produces a visible task or alert; the user is never left wondering whether a transaction succeeded. Inferred from the technical spec's explicit prohibition on silent failures (§13.2, rule 6).

3. Design Philosophy

The mental model for Integrated Payments is a payment drawer that travels with the patient record — staff never navigate away from their clinical or administrative context to take a payment. Whether the entry point is an appointment, an invoice, or a patient account page, the payment interaction layers over the existing view and returns the user to their starting context on completion. Inferred from the Payment Drawer concept described in §5.1.

Empty states should be informative and action-oriented: a patient with no payment history should see a clear prompt explaining that payments taken in-practice or online will appear here, not a blank panel. Inferred from the outstanding balances list and receipt history requirements in §5.3.

Error states must always name the next available action — retry, create a task, or contact support — because a failed payment in a clinical setting has immediate operational consequences. Silent or vague errors are prohibited by the technical spec (§13.2, rule 6).

AI suggestions in this module are strictly informational (activity summaries, option explanations). They are visually distinct from user-confirmed actions and cannot initiate or modify payment flows. The AI boundary is non-negotiable (§7).

Multi-step flows (split payment, refund with approval, virtual terminal) use a linear wizard pattern: one decision per step, with a clear back path up to the point of no return. Once a payment reaches Authorised state, forward-only navigation applies. Inferred from the state machine rules in §3.2 and the split payment and refund flow requirements in §4.4 and §5.1.

Read-only vs editable surfaces are clearly distinguished: the audit panel on a completed payment is always read-only; the payment drawer before initiation is editable. Captured or reconciled payments display in a locked state with no editable fields. Inferred from the lifecycle state machine (§3.2) and the immutable audit trail requirement (§8).

Undo/redo is not applicable to payment execution — financial transactions are governed by refund and void flows, not undo. The UX must make this clear at the point of confirmation. Inferred from §3.2 and §4.4.

4. Primary Surfaces

4.1 Web Portal

Who uses it: front-of-house staff, practice managers, compliance officers, and clinicians initiating or reviewing payments in the primary staff workspace. Inferred from §5.1 and §9 access control table.

Key tasks performed here:

• Initiate a terminal, pay-by-link, or virtual terminal payment from the Payment Drawer, opened from a patient account, appointment, or invoice context (§5.1).
• Select the target registered terminal for card-present payments (§4.1, §5.1).
• Monitor live payment status (Initiated → Awaiting Customer Action → Authorised → Captured / Failed) in the Payment Drawer's provider status panel (§5.1).
• Issue a pay-by-link for a specific invoice via the Pay-By-Link Composer and monitor delivery status (§4.2, §5.1).
• Use the virtual terminal (RBAC-restricted) for phone or remote card-not-present payments, with call-recording mute indicator where Telephony / AI Receptionist is enabled (§4.3, §5.1).
• Issue full or partial refunds with mandatory reason code; route through approval workflow for high-value actions (§4.4, §5.1).
• Configure and execute split payment tenders (§4.4, §5.1).
• View and filter payment history, exceptions, subscription status, and the refund and void log (§13.4).
• View the audit panel for any payment: actor, timestamp, action, and provider reference (§5.1).

Layout pattern: list-detail with a slide-over drawer. The primary workspace (patient account / appointment / invoice) occupies the main pane; the Payment Drawer slides over it as a layered panel, returning the user to context on close. Payment history and exception views use a filterable list-detail layout. Inferred from the Payment Drawer model described in §5.1 and the filtering requirements in §13.4.

4.2 Tablet App

Who uses it: reception staff and front-of-house at the point of care, using the tablet as a workflow companion rather than a payment processor. Inferred from §5.2.

Key tasks performed here:

• Initiate a "collect payment" flow from the patient context, routing to a terminal or pay-by-link (§5.2).
• Display live payment status once a collection flow has been initiated (§5.2).

Touch ergonomics: all interactive controls must meet a minimum tap target of 48 × 48 px to support use at a front desk where precision tapping may be limited. The tablet surface is companion-only — card entry never occurs here (§5.2). Inferred from §5.2 and the WCAG touch-target requirement in the technical spec's accessibility note (§14).

Layout pattern: action-card overlay within the existing patient or appointment view. The payment initiation action appears contextually; status feedback displays in-line. No dedicated payment screen is required on tablet. Inferred from the companion-role description in §5.2.

4.3 Mobile App (Patient)

Who uses it: patients managing their own outstanding balances, paying via app or pay-by-link, and reviewing receipt history. Inferred from §5.3.

Key tasks performed here:

• View outstanding balances and request amounts (§5.3).
• Initiate "Pay now" for a balance or a specific requested amount, including digital wallet payment where the provider supports it (§4.2, §5.3).
• Complete a one-time pay-by-link payment (§5.3).
• View receipt history (§5.3).

Layout pattern: vertical list with a bottom-sheet action surface. Outstanding balances are listed with clear amounts and due context; "Pay now" launches a bottom-sheet checkout flow. Receipt history is a reverse-chronological list. Inferred from mobile payment UX conventions and the outstanding balances list + receipt history requirements in §5.3.

5. Interaction Model

5.1 Primary Flows

The following primary flows are inferred from the payment execution capabilities (§4), delivery surfaces (§5), and system-initiated triggers (§4.6) described in the technical spec.

Flow 1 — In-practice terminal payment (staff-initiated)

1. Staff opens a patient account, appointment, or invoice context in the web portal or tablet app.
2. Staff opens the Payment Drawer (web) or initiates "collect payment" (tablet).
3. Staff confirms or adjusts the amount (invoice total, partial, or custom).
4. Staff selects "Terminal" as the payment method and selects the target registered terminal.
5. Payment Drawer transitions to Awaiting Customer Action — patient interacts with the physical terminal.
6. UI returns Authorised → Captured (success) or Failed (declined / timeout) from the provider.
7. On success: receipt delivery is triggered via Communication Hub; Payment Drawer shows "Send receipt" status.
8. On failure: exception banner displayed; task created via Task Manager; retry path offered.
9. Staff closes the Payment Drawer; returns to the originating context.

Flow 2 — Pay-by-link (staff-issued)

1. Staff opens the Pay-By-Link Composer from the Payment Drawer, linked to a specific invoice.
2. Staff confirms the amount and delivery method (app push, email, or SMS — defaulting to app-first).
3. Link is issued; Communication Hub delivers it.
4. Payment Drawer shows link delivery status and tracks link state (sent, opened, paid, expired).
5. On patient completion: payment status updates in Primoro and PMS; receipt delivered.

Flow 3 — Patient self-serve payment (mobile app)

1. Patient opens the app and navigates to outstanding balances or receives a pay-by-link.
2. Patient selects the balance or requested amount and taps "Pay now".
3. Hosted checkout presented (digital wallet option displayed where provider supports it).
4. On success: receipt available immediately in receipt history; PMS writeback triggered.
5. On failure: patient sees an inline error with a retry option; staff exception task created.

Flow 4 — Virtual terminal payment (RBAC-restricted staff)

1. RBAC-authorised staff opens the virtual terminal from the Payment Drawer.
2. Staff selects the patient and billable target; confirms amount.
3. Hosted card-entry fields are presented (tokenised; no raw card data).
4. Where Telephony / AI Receptionist is enabled, a call-recording mute indicator is displayed during card entry (§4.3).
5. On success: follows the same receipt and PMS writeback path as terminal payments.
6. On failure: exception path as per Flow 1, step 8.

Flow 5 — Refund or void (staff-initiated)

1. Staff opens a Captured payment record.
2. Staff selects "Refund" (full or partial) or "Void" (only available before Captured).
3. Staff selects a reason code from a controlled list (needs UX writer input — reason code list and labels).
4. If the action exceeds the practice-configured approval threshold, an approval request is routed; the UI displays a "Pending approval" state until an approver acts (§4.4, §9).
5. On approval (or if no approval required): refund or void is processed; state transitions to Refunded, Partially Refunded, or Voided / Cancelled.
6. Updated receipt delivered to patient; audit event logged.

Flow 6 — Split payment (staff-initiated)

1. Staff opens the Payment Drawer and selects "Split payment".
2. Staff adds tenders (card, cash, voucher) and allocates amounts; UI prevents under- or over-payment.
3. Each tender is confirmed in sequence.
4. On all tenders captured: a single settled outcome is recorded; multiple ledger entries created; receipt issued.

Flow 7 — Rewards credit applied at checkout

This flow is system-assisted rather than staff-driven — Rewards Manager passes the applicable credit amount and redemption reference before capture (§4.5).

1. During any checkout flow (terminal, online, virtual terminal), if Rewards Manager is enabled and a valid credit is available, the credit amount is displayed in the Payment Drawer before capture.
2. The net charge (after credit deduction) is shown clearly alongside the original amount and credit applied.
3. On successful capture: credit is shown in the receipt; redemption event returned to Rewards Manager.
4. If Rewards Manager is not enabled or no credit is available, this step does not appear (no dead toggle).

When Rewards Manager is enabled, Integrated Payments owns the redemption UX at the point of payment — the credit line in the Payment Drawer is the canonical place where a rewards credit is applied and confirmed. Staff do not need to visit Rewards Manager to apply a credit during a payment; the value is surfaced automatically in the drawer pre-capture and the confirmation modal includes the credit amount alongside the net charge. Rewards Manager retains ownership of the redemption ledger and history views; Integrated Payments is the execution surface only. This ensures there is no ambiguity about which module owns the in-payment redemption interaction when Integrated Payments is active. Inferred from Rewards Manager UX §4.1, §4.2, and §4.3 in conjunction with §4.5 and §6.1 of the technical spec.

Flow 8 — System-initiated payment (Smart Treatment Proposals acceptance)

Inferred from §4.6 — Integrated Payments receives a proposal acceptance event with PaymentProfileID and selected payment option.

1. Patient accepts a Smart Treatment Proposal carrying a PaymentProfileID.
2. Integrated Payments receives the acceptance event; pre-populates the payment method from the PaymentProfileID.
3. Selected payment option (deposit, staged payments, or finance referral) is applied:
4. Deposit and staged payment options route through the standard payment drawer flow with pre-filled values.
5. Finance referral routes to the third-party provider; outcome is recorded by Integrated Payments.
6. Staff sees the pre-populated payment ready for confirmation, not a blank form.

When a payment is initiated from a Smart Treatment Proposal acceptance event, the Payment Drawer must make the separation between payment and treatment commitment visually unambiguous. Accepting a payment option in the drawer confirms the financial transaction only; it does not constitute clinical acceptance of the proposed treatment. This distinction must be reinforced in the drawer's confirmation step — for example, the confirmation modal MUST NOT use language such as "Accept treatment" or imply that confirming payment is the same as approving the clinical proposal. The treatment acceptance is owned by Smart Treatment Proposals and has already occurred upstream; the payment step is exclusively financial. This constraint is inferred from Smart Treatment Proposals UX §2 (Principle 6) and §3 (Design Philosophy), which explicitly require that selection or payment of an option never implies or auto-commits to treatment acceptance. Integrated Payments MUST NOT reintroduce that ambiguity at the checkout step.

Flow 9 — Direct Debit mandate capture (subscription enrolment gate)

Inferred from Hygiene Subscriptions Technical Spec §5.3 and §17.2 rule 3, which make Direct Debit mandate setup a non-optional gate during subscription enrolment.

1. A subscription enrolment flow (Hygiene Subscriptions or Care Plan Subscriptions) triggers a mandate capture request to Integrated Payments, passing the patient context and the subscription reference.
2. Integrated Payments presents the mandate capture surface — either in-clinic via the tablet companion flow or deferred to the patient's mobile app — according to the enrolment surface in use.
3. In-clinic (tablet): staff initiate the mandate collection from the tablet's "collect payment" action card; the patient completes the GoCardless hosted mandate flow on the patient-facing surface. Staff see live mandate status in the provider status panel.
4. Deferred (mobile app): a pay-by-link–style mandate setup link is issued via Communication Hub; the patient completes mandate authorisation in the app or via the hosted flow; status updates in the patient account when authorised.
5. Mandate lifecycle states (Active mandate, Pending, Failed, Cancelled) are surfaced in the Subscription Status Badge in the patient account view. A Failed mandate state is displayed immediately and prominently — an exception banner appears in the patient account and the exceptions queue without requiring staff to navigate to a separate view (§3.3).
6. If mandate capture fails at the enrolment gate, the enrolment flow is blocked and a task is created via Task Manager with the failure reason and a link to the patient record. Staff see a clear recovery path: retry mandate capture, issue a fresh mandate link, or escalate. The patient is not enrolled until a valid, active mandate is confirmed.
7. Mandate capture is governed by the same "money is irreversible" and "no silent failures" principles as payment execution — every mandate state transition is audited and actor-attributed.

Flow 10 — Dashboard-initiated payment (Smart Dashboards entry point)

Inferred from Smart Dashboards §4.1 and §4.4, which list "taking a payment" as an inline action available to FOH staff directly from the dashboard view.

1. A front-of-house staff member triggers a "Take payment" inline action from a patient or appointment card on the Smart Dashboard.
2. The Payment Drawer opens as a slide-over panel layered over the dashboard view — identical in behaviour to opening the drawer from a patient account or appointment context. No navigation away from the dashboard occurs.
3. The drawer is pre-populated with the patient context and any outstanding balance surfaced by the dashboard card. Staff confirm or adjust the amount and proceed through the standard payment flow (terminal, pay-by-link, or virtual terminal).
4. On successful capture, the Payment Drawer closes and the staff member returns to the dashboard. The dashboard card for the relevant patient or appointment updates to reflect the settled payment state.
5. On failure, the exception banner is displayed within the drawer (not the dashboard surface); a task is created via Task Manager; the drawer remains open with a retry path. The dashboard card reflects the outstanding balance until the exception is resolved.
6. All reversibility and editing constraints apply identically to dashboard-initiated payments as to any other entry point — once Authorised, forward-only navigation applies and amount editing is disabled. The dashboard entry point does not create a separate or relaxed payment flow.

Flow 11 — Care plan subscription payment with billing-trust pre-explanation

Inferred from Care Plan Subscriptions UX §2 (billing trust principle), which requires that any change affecting what a patient pays, or when, must be explained before it takes effect.

1. When a payment is triggered in connection with a care plan subscription — whether a scheduled instalment, a proration adjustment following a plan change, or a first payment at enrolment — the Payment Drawer or hosted checkout surface MUST display a clear pre-payment explanation before the confirmation step. This explanation includes: what is being charged, why (e.g. "First month's care plan fee", "Proration adjustment following plan upgrade on [date]"), and the amount.
2. Proration notices are surfaced as a discrete labelled line item in the Payment Drawer — not buried in a tooltip or accessible only via progressive disclosure — so that staff processing the payment in-clinic, and patients paying online, both see the adjusted amount in context before confirming.
3. If a care plan payment fails (scheduled or otherwise), the exception handling follows the standard Failed state pattern: exception banner in the patient account, task created via Task Manager, and a clear retry or mandate-update path offered. The failed payment record must identify the care plan subscription reference so staff can locate the relevant subscription record without cross-referencing manually.
4. Staff MUST NOT be able to confirm a care plan-linked payment without the pre-explanation step being surfaced. The confirmation modal is only reachable after the billing context screen has been presented and acknowledged (even if acknowledgement is implicit via a "Continue" action).

Flow 12 — Product Shop order payment (payment failure and abort-and-retry)

Inferred from Product Shop UX §2 ("Payment integrity at every step") and §3 (prohibition on showing an order to the patient before payment is confirmed), in conjunction with §3.1 and §6.1 of the technical specification.

1. When a payment is initiated for a Product Shop order, the Payment Drawer displays the product order reference as the billable target (rather than a PMS invoice reference). The patient does not see an order confirmation until the payment reaches Captured state.
2. If the payment fails at any point before Captured, the Failed state pattern applies: an exception banner is displayed, a task is created via Task Manager, and a retry path is offered. The product order is held in an unpaid state — it is never surfaced to the patient as confirmed.
3. The retry path for a failed Product Shop payment presents the same order reference and amount, without requiring staff to re-enter order details. Staff confirm the retry from the Payment Drawer; the order context persists until the payment is either captured or explicitly abandoned.
4. If a payment is abandoned (staff cancels without retrying), the order is returned to an unpaid/voided state and the patient is not notified of an order confirmation. Staff are prompted to confirm the abandonment explicitly — this is a deliberate destructive action consistent with the "money is irreversible" principle applied to the order lifecycle.
5. This abort-and-retry pattern is the mechanism by which Integrated Payments supports Product Shop's "payment integrity at every step" mandate. No order confirmation is shown, no fulfilment is triggered, and no communication is sent to the patient until Captured state is reached and confirmed.

5.2 State Machines (Mirror of Technical Spec § 3)

The following UX treatments mirror the Payment Lifecycle State Machine defined in §3.2 of the technical specification.

State treatment principles inferred from §3.2 state machine rules and §5.1 Payment Drawer description:

• Once a payment reaches Authorised or beyond, the Payment Drawer enters a forward-only mode — back navigation and amount editing are disabled (§3.2 enriched rule).
• Irreversible transitions (Refund, Void) always present a confirmation modal with the reason code selector before executing (§4.4).
• The Failed state always surfaces a labelled retry action and a "Create task" shortcut — never a dead end (§13.2, rule 6).
• The Reconciled state renders the full payment record as read-only with no editable fields (§6.3 PMS boundary).

The Subscription Status Model (§3.3) surfaces the following states in the patient account and subscription views, read-only, sourced from GoCardless:

A Failed subscription payment state must be surfaced without delay and without requiring staff to navigate to a separate view — an exception banner or task card should appear in the patient account and in the exceptions queue (§3.3).

5.3 Empty / Loading / Error / Offline States

The following state treatments are inferred from the module's surfaces (§5), the prohibition on silent failures (§13.2 rule 6), and standard progressive-disclosure practice.

Payment history list (web portal and patient app)

• Empty state: (needs UX writer input — label and supporting text explaining that payments taken in-practice or online will appear here)
• Loading state: skeleton rows matching the list layout; no spinner replacing the whole screen
• Error state: inline error message with a retry action; if the error persists, a link to raise a support task
• Offline state (patient app): cached receipt history is visible read-only; "Pay now" is disabled with an explanatory label (needs UX writer input)

Payment Drawer (web portal)

• Empty / pre-initiation: amount selector and method selector are active; no status panel shown until Initiated
• Loading state: provider status panel shows an animated in-progress indicator with the last known state labelled
• Error state: Failed badge with provider error description (where available), retry action, and "Create task" shortcut
• Offline state: drawer is disabled; (needs UX writer input — message explaining that payments require connectivity)

Terminal awaiting state

• A timeout countdown or elapsed-time indicator should be displayed during the Awaiting Customer Action state so staff are not left uncertain whether the terminal is still active. Inferred from the provider timeout requirement in §3.2 and the real-time feedback requirement in §14. (needs UX writer input — timeout copy and recovery prompt)

Subscription status panel

• Empty state: shown only when subscription modules are enabled; not displayed otherwise (no dead toggle)
• Loading state: skeleton matching the status layout
• Error state: inline error with a retry; failed subscription status is prominently badged even during an error recovery
• Offline state: last known subscription status displayed with a staleness indicator

6. Component Inventory

New components introduced or extended by this module:

• Payment Drawer — slide-over panel for payment initiation, status monitoring, and audit review; appears in patient account, appointment, and invoice contexts on web portal (§5.1).
• Provider Status Panel — embedded within the Payment Drawer; displays live lifecycle state transitions (Initiated → Authorised → Captured / Failed) with animated in-progress and terminal state badges (§5.1).
• Terminal Selector — dropdown or radio-group control within the Payment Drawer for selecting a registered terminal per site; hidden when terminal method is not selected (§4.1, §5.1).
• Pay-By-Link Composer — form surface within the Payment Drawer for configuring and issuing invoice-specific pay-by-link URLs; includes delivery method selector and link status tracker (§4.2, §5.1).
• Virtual Terminal Panel — RBAC-gated panel within the Payment Drawer surfacing hosted/tokenised card-entry fields; includes call-recording mute indicator where Telephony / AI Receptionist is enabled (§4.3, §5.1).
• Split Payment Tender Builder — multi-row tender allocation UI within the Payment Drawer; enforces under/over-payment prevention in real time (§4.4, §5.1).
• Refund / Void Form — stepped form within the Payment Drawer for issuing refunds or voids; includes mandatory reason code selector and approval-state display (§4.4, §5.1).
• Rewards Credit Line — read-only line item displayed in the Payment Drawer and receipt when a rewards credit has been applied; shows credit amount and net charge (§4.5).
• Subscription Status Badge — compact read-only indicator surfacing GoCardless subscription payment state within the patient account view (§3.3, §5.4).
• Payment Exception Banner — contextual alert banner surfaced in patient account, appointment, and exception queue views when a payment or subscription payment has failed (§5.4).
• Payment Audit Panel — read-only log panel within the Payment Drawer showing actor, timestamp, action, and provider reference for every lifecycle event on a payment record (§5.1, §8).
• Outstanding Balances List (patient app) — reverse-chronological list of unpaid balances and payment requests, each with a "Pay now" action (§5.3).
• Receipt History List (patient app) — reverse-chronological list of completed payment receipts, accessible offline for cached items (§5.3).
• Billing Context Panel — pre-confirmation panel displayed within the Payment Drawer for care plan and subscription-linked payments; presents a structured explanation of what is being charged, why, and the amount (including proration adjustments) before the confirmation step is reachable. Inferred from Care Plan Subscriptions UX §2 billing trust principle.
• Mandate Capture Status Panel — embedded within the Payment Drawer and patient account view; displays the live mandate lifecycle state (Pending, Active, Failed, Cancelled) during and after Direct Debit mandate setup for subscription enrolment flows. Inferred from Hygiene Subscriptions Technical Spec §5.3 and §17.2 rule 3.

Reused from the design system:

• Modal / confirmation dialog — used for irreversible action confirmation (refund, void, high-value approval)
• Toast notification — used for non-critical confirmations (receipt sent, link issued)
• Badge / status chip — repurposed for payment lifecycle states and subscription states
• Filterable data table — payment history and exception views (§13.4)
• Form field with programmatic label — amount selector, reason code selector, tender allocation fields
• Task card — surfaced via Task Manager integration for failed payments and fallback writeback (§6.2)

7. Visual Design Notes

(This section records semantic intent only. Specific typographic scales, colour hex values, and component library names are outside the scope of this UX specification and require visual design input.)

• Colour — semantic usage: payment lifecycle states should use the platform's semantic colour system: success (Captured, Paid), warning (Partially Refunded, Payment Pending), error (Failed), neutral/resolved (Reconciled, Voided / Cancelled, Refunded). The Failed state — for both payments and subscription payments — must be visually unambiguous given its downstream operational impact (§3.2, §3.3).
• Iconography: payment method icons (card, terminal, digital wallet, direct debit) should be used alongside labels — never icon-only. The call-recording mute indicator in the virtual terminal must include a visible label, not only an icon, to ensure it is not overlooked during a live call (§4.3).
• Monospace typography: payment amounts, provider reference IDs, and audit timestamps should use monospace or tabular-figures styling to support scanning and comparison in the audit panel and payment history table (§5.1, §8).
• Read-only visual distinction: Captured, Reconciled, and other terminal-state payment records should have a clearly distinct visual treatment from in-progress or editable records — e.g. a locked or greyed-out form surface — to prevent staff from attempting edits that are not available (§3.2).
• Motion: transitions are used only where they communicate state change (e.g. the provider status panel animating through Initiated → Authorised → Captured). Nothing is animated for decoration. The prefers-reduced-motion media query must be respected throughout.

8. Accessibility & Inclusivity

The module MUST meet WCAG 2.2 AA. Specifically:

• Text contrast ≥4.5:1 (normal) / ≥3:1 (large)
• All interactive controls reachable via keyboard
• Focus states visible
• Form fields have programmatic labels
• ARIA used only where native semantics are insufficient
• Touch targets ≥44×44 px on mobile/tablet
• Motion can be reduced via prefers-reduced-motion
• Screen reader tested on NVDA (Windows), VoiceOver (macOS/iOS), and TalkBack (Android)

Module-specific accessibility considerations:

• The provider status panel transitions between states in real time. State changes must be announced to screen readers via a live region (e.g. aria-live="polite" for status updates; aria-live="assertive" for the Failed state). Inferred from the real-time terminal status feedback requirement (§4.1, §14).
• The call-recording mute indicator in the virtual terminal must be perceivable without relying on colour alone — an icon plus text label is required (§4.3).
• The Payment Drawer is a slide-over panel; focus management must trap focus within the drawer while it is open and return focus to the trigger element on close, in line with ARIA dialog pattern requirements. Inferred from the drawer surface described in §5.1.
• Reason code selectors in the refund and void flow must be implemented as accessible select or radio-group controls with visible, programmatic labels — not unlabelled dropdowns. Inferred from the mandatory reason code requirement (§4.4).
• The outstanding balances list and receipt history in the patient app must be usable with VoiceOver on iOS and TalkBack on Android, given that patients are the primary users of those surfaces (§5.3).

9. Internationalisation

• Locale-aware date/time/number formatting
• All user-facing strings externalised
• Layouts tolerant of 30% string-length growth (German, French)
• RTL support: not defined in the technical specification. (needs UX writer input — confirm whether RTL is required for this module's target market) Inferred as unresolved from the absence of any RTL reference in the technical spec.
• Currency formatting must use locale-appropriate symbol placement and decimal conventions. The module operates in UK context (DNA Payments is a UK acquirer — §1), but multi-locale formatting should be applied by default as a platform standard. Inferred from §1 provider model and the platform's locale-aware standard.
• Payment amounts displayed in the audit panel and financial history must use consistent locale-aware number formatting with tabular figures to prevent misreading of financial values across locales. Inferred from §8 and §13.4.

10. Cross-Module UX Touchpoints

All touchpoints below are inferred from the integration contracts in §6 and §10 of the technical specification.

• Appointment Manager — when a deposit collection event is triggered by Appointment Manager, the staff user sees a Payment Drawer pre-populated with the deposit amount and the appointment context. The handoff is system-initiated; staff confirm and execute. The user does not navigate away from the appointment view (§4.6, §6.1).
• Communication Hub — receipt delivery status and pay-by-link delivery status are surfaced inline in the Payment Drawer via Communication Hub. Staff see "Receipt sent via app" / "Receipt sent via email" confirmation without leaving the payment context. All communications are logged and visible in Communication Hub's own audit surface (§4.1, §4.2, §6.2).
• Task Manager — failed payments, failed PMS writeback events, and pending approval actions surface as task cards in Task Manager. The Payment Drawer provides a "Create task" shortcut on failure; tasks created automatically by the system link back to the originating payment record. Staff move between the payment record and the task card via contextual links (§5.4, §6.2).
• Financial Insights — reconciliation indicators are surfaced in Financial Insights dashboards when the module emits Financial Signal events. Staff navigating to Financial Insights see payment data attributed by site and staff member. The transition from a payment record to a Financial Insights report is a navigational handoff, not an embedded surface (§5.4, §6.2, §7.3).
• Rewards Manager — the rewards credit line in the Payment Drawer is populated by Rewards Manager pre-capture. Staff and patients see the credit applied and the net amount without needing to navigate to Rewards Manager. Post-capture, the redemption event is emitted silently; no staff action is required (§4.5, §6.1, §6.2). When Integrated Payments is active, it is the execution surface for all in-payment reward redemptions; Rewards Manager retains ownership of the redemption ledger and history. See Flow 7 for the full in-payment redemption UX.
• Smart Treatment Proposals — when a patient accepts a treatment proposal, the Payment Drawer opens pre-populated with the payment method from the PaymentProfileID and the selected payment option. Staff see a "ready to confirm" state rather than a blank form, reducing the risk of errors in high-value treatment payment flows. The confirmation step within the drawer uses language that is exclusively financial — it must not suggest or imply clinical acceptance of the proposal, which has already occurred upstream (§4.6, §6.1). See Flow 8 for the full treatment-proposal payment UX and the payment/treatment separation constraint.
• Care Plan Subscriptions / Hygiene Subscriptions — a Failed subscription payment badge in the patient account view signals to staff that the relevant subscription module has gated fulfilment. Integrated Payments surfaces this state; the staff action (contacting the patient, updating payment details) is owned by the subscription modules. The visual treatment must make the handoff direction clear — this is a status to act on, not a payment to retry directly (§3.3, §6.2). For Direct Debit mandate capture during subscription enrolment, Integrated Payments owns the mandate collection UX and lifecycle (see Flow 9). For care plan-linked payments, the Billing Context Panel must surface a pre-confirmation explanation of any charge or proration adjustment before the confirmation step is reachable (see Flow 11).
• Smart Dashboards — FOH staff can initiate a "Take payment" inline action directly from a Smart Dashboard patient or appointment card. This opens the standard Payment Drawer as a slide-over over the dashboard; the full payment flow, state machine, and reversibility constraints apply identically to dashboard-initiated payments as to any other entry point. On completion or failure, the staff member returns to the dashboard context. See Flow 10 for the full dashboard-initiated payment UX. Inferred from Smart Dashboards §4.1 and §4.4.
• Access Manager — RBAC-restricted controls (virtual terminal, high-value refund) are hidden entirely when the current user's role does not permit them — not shown in a disabled state. Role and permission context is visible in the platform header. Inferred from the "no dead toggles" principle and §9 access control table.
• AI Guardian — AI Guardian reads payment lifecycle state signals silently. There is no user-facing touchpoint for this integration in normal operation. If AI Guardian surfaces a payment-related summary or alert in its own UI, it must be clearly attributed as an AI summary and must not include any card data (§7).
• Product Shop — commerce order payments initiated from Product Shop arrive as a valid billable target in the Payment Drawer. The payment context shows the product order reference rather than a PMS invoice reference. Staff see the same drawer experience; the difference is the billable target type displayed (§3.1, §6.1). Payment failure handling for Product Shop orders follows the abort-and-retry pattern described in Flow 12; no order confirmation is surfaced to the patient until Captured state is reached.
• Lab Manager — lab invoices generated by Lab Manager may be surfaced as a billable target in the Payment Drawer, using the lab invoice reference in place of a PMS invoice reference. Where a lab invoice is payable via Integrated Payments, the same drawer experience applies: staff confirm the amount, select the payment method, and the payment proceeds through the standard lifecycle. Lab invoice payment status (paid, outstanding, failed) is visible on the payment record with the lab invoice reference so staff can cross-reference Lab Manager without manual lookup. If lab invoices are reconciled separately and are not payable via Integrated Payments in the current configuration, the Payment Drawer does not surface them as a billable target — the control is not rendered (no dead toggle). (Needs product decision on whether lab invoices are a supported billable target type in the initial release; see Open Questions.) Inferred from Lab Manager §4.1 and §4.4 in conjunction with §4.2 and §3.1 of the technical specification.
• PMS — PMS writeback is invisible to the user when successful. On writeback failure, a task is created and an exception indicator appears on the payment record, prompting staff to reconcile manually. The payment record shows writeback status as a discrete field (§6.3).

UX consistency rules:

• The Payment Drawer is the single entry point for all staff-initiated payment actions across the web portal; no payment flows exist outside it (§5.1).
• Exception banners for failed payments and failed PMS writeback follow the same visual pattern as exception banners in other modules — same component, same position, same dismissal behaviour — to avoid creating a separate "payments look" for alerts (§5.4).
• RBAC-restricted controls are never shown in a disabled state to users without the required role — they are not rendered at all. This is consistent with the "no dead toggles" principle and must be applied uniformly across all surfaces (§9, §5.1).
• Action buttons in the Payment Drawer follow the platform-standard positioning: primary action bottom-right on tablet, top-right on web portal (implied by platform conventions for action-first layout).

11. Governance & Auditability

All governance and auditability requirements are inferred from §8, §9, and §7 of the technical specification.

• AI activity is visually distinct from user actions. AI-generated summaries of payment activity are labelled with an AI badge and a distinct visual container (e.g. a dotted border or named "AI summary" label). AI cannot initiate, modify, or cancel payments; if an AI summary is displayed adjacent to a payment action, the action button is clearly attributable to the human user, not the AI (§7).
• Audit-significant actions show a confirmation step. Refunds, voids, split payment completions, high-value approval actions, and rewards credit applications all present a confirmation modal before execution. The confirmation modal displays the action being taken, the actor, and the amount or credit involved (§4.4, §4.5, §8).
• The Payment Audit Panel is always accessible from a payment record. It shows: who initiated each action (named staff member or "patient self-serve"), when (UTC timestamp), where (site ID and terminal ID where applicable), what (amount, method, billable target type and reference), and the provider reference ID. The panel is read-only and cannot be edited or deleted (§5.1, §8).
• Approval state is visible. Where a refund or void requires approval, the payment record displays a "Pending approval" badge with the approver role identified. The approver sees an action card in their Task Manager queue. Approval and denial are both logged with actor and timestamp (§4.4, §9, §8).
• Read-only states are visually distinct from editable. Captured, Reconciled, and Refunded payment records are displayed in a locked visual state; no input fields are active. Inline labels indicate why the record is locked (e.g. "Payment captured — no further edits available") (needs UX writer input — exact locked-state label).
• The current user's role and active permissions are visible in the platform header. This is a platform-wide standard; Integrated Payments surfaces RBAC-restricted controls (virtual terminal, high-value refund approval) only to users whose role permits them, with no disabled ghost controls visible to others (§9).
• Audit log export is accessible to compliance and admin roles from the payment history view. The export action is available as a discrete control rather than buried in settings. (needs UX writer input — export format options and confirmation copy) (§8 enriched requirement).

12. Notification & Communication Patterns

All notification patterns are inferred from §5.4, §6.2, §8, and the integration with Communication Hub described in §4.1, §4.2, and §10.

• In-app banner (staff web portal and tablet app): displayed for failed payments, failed PMS writeback, subscription payment failures, and pending high-value refund approvals. Banners are persistent (not auto-dismissing) for payment failures and exceptions — they remain until the staff member takes action or dismisses explicitly. Inferred from the exception banner requirement in §5.4 and the prohibition on silent failures in §13.2.
• Toast (staff web portal and patient app): used for transient confirmations — receipt sent, pay-by-link issued, rewards credit applied, refund processed successfully. Toasts are auto-dismissing and do not require action. Inferred from the non-critical confirmation nature of these events and standard calm-by-default UX practice.
• Push notification (patient mobile app, delivered via Communication Hub — NOT directly): used for pay-by-link delivery (primary channel, app-first), receipt delivery after successful payment, and payment failure notifications where the patient needs to take action (e.g. re-attempt payment). All push notifications are routed through Communication Hub; Integrated Payments emits a delivery trigger event only (§4.2, §6.2).
• Email / SMS (delivered via Communication Hub — NOT directly): used as fallback channels for pay-by-link delivery and receipt delivery when the patient does not have the app or push notifications disabled. Integrated Payments emits a delivery trigger event to Communication Hub with channel preference; Communication Hub selects the fallback channel. All communications are logged in Communication Hub (§4.2, §6.2).
• Task notifications (via Task Manager): generated automatically for failed payment exceptions, failed PMS writeback requiring manual reconciliation, pending high-value refund approvals, and subscription payment failures requiring staff follow-up. Task cards link back to the originating payment record. Inferred from §5.4, §6.2, and §13.2 rules 6 and 13.

13. Open Questions

The following UX decisions must be resolved before this specification is promoted from draft to published. Several directly mirror open questions in the technical specification.

1. Approval threshold UX: The approval workflow for high-value refunds is configurable at practice level (technical spec §15, Q3). The UX must define: how the threshold is communicated to the staff member attempting the refund before they complete the reason-code step, and whether the threshold amount is displayed in the Payment Drawer. (Blocked on technical spec Q3 resolution.)

2. Terminal timeout treatment: The technical specification requires provider timeouts to surface as Failed with a retry path (§3.2). The UX must define: whether a countdown timer or elapsed-time indicator is shown during Awaiting Customer Action, and what copy and recovery prompt appear on timeout. (needs UX writer input — timeout duration and copy)

3. Finance referral handoff UX: For Smart Treatment Proposal acceptance events where the selected option is a finance referral, the patient is routed to a third-party finance provider (§4.6). The UX must define: the handoff pattern (in-app webview, external browser, or redirect), what the staff member sees during and after the referral, and how the outcome is surfaced on return. (Blocked on technical spec Q4 — third-party finance providers not yet named.)

4. Pay-by-link expiry UX: The technical spec does not define a pay-by-link expiry period. The UX must define: whether an expiry date is shown to staff in the Pay-By-Link Composer, what the patient sees when a link has expired, and how staff are notified of an expired unpaid link. (Needs product decision on expiry policy.)

5. Rewards credit visibility for patients: The technical spec requires the rewards credit to be reflected in the patient-facing receipt (§4.5). The UX must define: whether the credit is also surfaced during the checkout flow (before the patient taps "Pay now") and how it is labelled. (needs UX writer input — credit label and receipt line-item copy)

6. Offline behaviour — patient app payment initiation: The outstanding balances list is intended to be available offline (inferred from receipt history cache pattern in §5.3), but payment initiation requires connectivity. The UX must define the exact offline treatment: which elements are cached, how staleness is communicated, and whether a partial balance view is shown or the list is hidden entirely. (Needs product and engineering input.)

7. PMS writeback status visibility to staff: The technical spec requires a fallback task when PMS writeback fails (§6.3). The UX must define: whether the writeback status is surfaced as a discrete field on every payment record (e.g. "PMS: Written back ✓ / Pending reconciliation"), or only when it has failed. (Needs product decision on default visibility level.)

8. GoCardless fee data display: The technical spec requires GoCardless fee data to be included in PMS writeback payloads for subscription payments (§2.1, §13.2 rule 13). The UX must define: whether fee data is surfaced in the subscription status panel or payment record visible to staff, or only included in the writeback payload for Finance Module reconciliation without a staff-facing display. (Needs product decision.)

9. RTL language support: Not addressed in the technical specification. Confirm whether right-to-left layout support is required for this module's target market before visual design begins. (Needs product input.)

10. Data retention and subject erasure UX: The technical spec flags GDPR retention obligations (§14 Privacy, Q1) as unresolved. Once the retention policy is defined, the UX must determine whether patients or compliance staff have any in-app surface for data subject access requests or erasure requests related to payment records. (Blocked on technical spec Q1 and Q6 resolution.)

11. Lab invoice as a billable target type: Lab Manager §4.1 and §4.4 reference lab invoice objects and reconciliation flows. The UX must confirm whether lab invoices are a supported billable target type in the Payment Drawer for the initial release, or whether lab invoice payments are handled outside Integrated Payments. If supported, the billable target display label and reference format must be defined. (Needs product decision; see Lab Manager touchpoint in §10.)

12. Direct Debit mandate capture surface — in-clinic vs deferred split: Flow 9 defines two mandate capture paths (in-clinic tablet and deferred mobile). The UX must confirm: whether both paths are supported in the initial release, what the patient-facing hosted mandate flow looks like on mobile, and whether the deferred mandate link follows the same delivery and expiry rules as pay-by-link. (Needs product and engineering input; blocked on GoCardless hosted mandate flow confirmation.)

13. Care plan proration notice — acknowledgement requirement: Flow 11 requires the Billing Context Panel to be acknowledged before the confirmation modal is reachable. The UX must define: whether acknowledgement is implicit (a "Continue" action advances past the panel) or explicit (a checkbox or active confirmation is required), and whether proration notices above a certain threshold require a stronger acknowledgement pattern. (Needs product decision aligned with Care Plan Subscriptions module.)