CI deploy 84761d0

Dockerfile

@@ -50,6 +50,9 @@ RUN pip install -e .
 # The built React SPA (served by api/main.py at / with hashed assets under /assets).
 COPY --from=web /web/dist ./web/dist
 
+# Non-sensitive build metadata for GET /version (CI overwrites with the real commit).
+COPY build_info.json ./
+
 # Writable dirs for weights + caches (owned so the Space's non-root user can write).
 RUN mkdir -p /app/checkpoints /app/.cache && chmod -R 777 /app/checkpoints /app/.cache
 

amanpay/version.py

@@ -0,0 +1,36 @@
+"""Non-sensitive build/version info. Torch-free so it is unit-testable in the
+light-dependency CI job. Never returns tokens, secrets, DB/Redis URLs, or env values."""
+
+from __future__ import annotations
+
+import json
+import os
+
+APP_VERSION = "1.0.0"
+
+
+def read_build_info(root_dir: str) -> dict:
+    """Load build_info.json (written by CI into the deploy bundle) or {} if absent."""
+    path = os.path.join(root_dir, "build_info.json")
+    try:
+        with open(path) as fh:
+            data = json.load(fh)
+            return data if isinstance(data, dict) else {}
+    except Exception:
+        return {}
+
+
+def build_version_info(root_dir: str, *, ui_mode: str = "react",
+                       provider_mode: str = "mock") -> dict:
+    """Assemble the /version payload. Only build metadata + operating mode — no secrets."""
+    bi = read_build_info(root_dir)
+    return {
+        "app_version": APP_VERSION,
+        "commit": bi.get("commit", "dev"),
+        "build_time": bi.get("build_time"),
+        "frontend": bi.get("frontend", APP_VERSION),
+        "backend": APP_VERSION,
+        "ui_mode": ui_mode,
+        "provider_mode": provider_mode,
+        "non_custodial": True,
+    }

api/main.py

@@ -173,3 +173,18 @@ def app_icon(size: str):
 @app.get("/info", include_in_schema=False)
 def info() -> dict:
     return {"name": "AmanPay Biometric API", "docs": "/docs", "health": "/health"}
+
+
+@app.get("/version")
+def version() -> dict:
+    """Non-sensitive build/version info for deploy verification and the UI footer.
+    Contains NO tokens, secrets, DB/Redis URLs, or env values."""
+    from amanpay.version import build_version_info
+    try:
+        from amanpay.payments.registry import provider_name_for
+        provider_mode = provider_name_for("SA")
+    except Exception:
+        provider_mode = "mock"
+    return build_version_info(_ROOT,
+                              ui_mode="react" if _use_react() else "legacy",
+                              provider_mode=provider_mode)

build_info.json

@@ -0,0 +1 @@
+{"commit":"84761d0","build_time":"2026-07-12T07:47:41Z","frontend":"1.0.0"}

web/src/App.tsx

@@ -1,20 +1,30 @@
 import { useEffect, useState } from 'react'
 import { EnrollPage } from './pages/EnrollPage'
 import { PayPage } from './pages/PayPage'
+import { NotFoundPage } from './pages/NotFoundPage'
+import { AppFooter } from './components/AppFooter'
+import { useSession } from './hooks/useSession'
 import { useI18n } from './i18n'
 import { Button } from './components/ui'
 
-type Route = 'pay' | 'enroll'
+type Route = 'pay' | 'enroll' | 'notfound'
+type NavTarget = 'pay' | 'enroll'
 
-function useHashRoute(): [Route, (r: Route) => void] {
-  const parse = (): Route => (window.location.hash.replace('#/', '') === 'enroll' ? 'enroll' : 'pay')
+function parse(): Route {
+  const raw = window.location.hash.replace(/^#\/?/, '')
+  if (raw === '' || raw === 'pay') return 'pay'
+  if (raw === 'enroll') return 'enroll'
+  return 'notfound'
+}
+
+function useHashRoute(): [Route, (r: NavTarget) => void] {
   const [route, setRoute] = useState<Route>(parse())
   useEffect(() => {
     const onHash = () => setRoute(parse())
     window.addEventListener('hashchange', onHash)
     return () => window.removeEventListener('hashchange', onHash)
   }, [])
-  const nav = (r: Route) => {
+  const nav = (r: NavTarget) => {
     window.location.hash = `#/${r}`
     setRoute(r)
   }
@@ -23,6 +33,7 @@ function useHashRoute(): [Route, (r: Route) => void] {
 
 export function App() {
   const { t, locale, setLocale } = useI18n()
+  const { activeUser } = useSession()
   const [route, nav] = useHashRoute()
   return (
     <div className="app">
@@ -36,14 +47,23 @@ export function App() {
             {t('nav.enroll')}
           </button>
         </nav>
-        <Button onClick={() => setLocale(locale === 'ar' ? 'en' : 'ar')} aria-label={t('lang.toggle')}>
-          {t('lang.toggle')}
-        </Button>
+        <div className="topbar-right">
+          <span className="active-user" title={activeUser ? activeUser.userId : ''}>
+            {activeUser ? t('header.activeUser', { user: activeUser.userId }) : t('header.noUser')}
+          </span>
+          <Button onClick={() => setLocale(locale === 'ar' ? 'en' : 'ar')} aria-label={t('lang.toggle')}>
+            {t('lang.toggle')}
+          </Button>
+        </div>
       </header>
+      <p className="demo-banner" role="note">{t('demo.banner')}</p>
       <main className="content">
         <p className="tagline">{t('app.tagline')}</p>
-        {route === 'pay' ? <PayPage /> : <EnrollPage />}
+        {route === 'pay' && <PayPage onNavEnroll={() => nav('enroll')} />}
+        {route === 'enroll' && <EnrollPage />}
+        {route === 'notfound' && <NotFoundPage onNav={nav} />}
       </main>
+      <AppFooter />
     </div>
   )
 }

web/src/api/auth.ts

@@ -1,15 +1,17 @@
 import { apiRequest } from './client'
-import { setToken } from '../auth/session'
+import { setActiveUser, setToken } from '../auth/session'
 import {
   serializeAssertion, serializeRegistration, toCreationOptions, toRequestOptions,
   isWebAuthnSupported, PasskeyCancelled, PasskeyUnsupported,
 } from '../auth/passkey'
 import type { DemoSeedResponse, EnrollResponse } from '../types'
 
-/** "Register / log in" for the demo: seed a tri-modal identity and receive a session token. */
+/** "Load demo identity": seed a tri-modal identity, receive a session token, and
+ *  mark this user as the active session user (used by the payment flow). */
 export async function demoSeed(userId: string): Promise<DemoSeedResponse> {
   const r = await apiRequest<DemoSeedResponse>('/demo/seed', { body: { user_id: userId } })
   if (r.token) setToken(r.token)
+  setActiveUser({ userId: r.user_id, via: 'demo' })
   return r
 }
 
@@ -59,5 +61,9 @@ export async function authenticatePasskey(userId: string): Promise<boolean> {
   const r = await apiRequest<{ success: boolean }>('/webauthn/authenticate/complete', {
     body: { user_id: userId, credential: serializeAssertion(cred) },
   })
+  // Passkey login establishes the active user for the payment flow. The demo backend
+  // does not require AMANPAY_REQUIRE_AUTH in this trusted environment, so a bearer
+  // token is optional here; the active user is what the Pay page uses.
+  if (r.success) setActiveUser({ userId, via: 'passkey' })
   return !!r.success
 }

web/src/api/payments.ts

@@ -37,6 +37,15 @@ export async function cancelPayment(paymentId: string): Promise<PaymentView> {
   return apiRequest<PaymentView>(`/payments/${encodeURIComponent(paymentId)}/cancel`, { method: 'POST', body: {} })
 }
 
+/** Refund via the real Payment Core refund API (amount in minor units / halalas).
+ *  Omit amountMinor for a full refund of the remaining balance. */
+export async function refundPayment(paymentId: string, amountMinor?: number, reason?: string): Promise<PaymentView> {
+  const body: Record<string, unknown> = {}
+  if (amountMinor !== undefined) body.amount_minor = amountMinor
+  if (reason) body.reason = reason
+  return apiRequest<PaymentView>(`/payments/${encodeURIComponent(paymentId)}/refund`, { method: 'POST', body })
+}
+
 export async function getProviders(): Promise<ProvidersResponse> {
   return apiRequest<ProvidersResponse>('/payments/providers')
 }

web/src/api/version.ts

@@ -0,0 +1,7 @@
+import { apiRequest } from './client'
+import type { VersionInfo } from '../types'
+
+/** Non-sensitive build/version info for the footer and deploy verification. */
+export async function getVersion(): Promise<VersionInfo> {
+  return apiRequest<VersionInfo>('/version')
+}

web/src/auth/session.test.ts

@@ -0,0 +1,24 @@
+import { describe, it, expect, beforeEach } from 'vitest'
+import {
+  getActiveUser, getToken, isAuthenticated, logout, setActiveUser, setToken,
+} from './session'
+
+describe('session (in-memory token + active user)', () => {
+  beforeEach(() => logout())
+
+  it('tracks the active user', () => {
+    expect(getActiveUser()).toBeNull()
+    setActiveUser({ userId: 'bob', via: 'demo' })
+    expect(getActiveUser()).toEqual({ userId: 'bob', via: 'demo' })
+  })
+
+  it('logout clears BOTH token and active user', () => {
+    setToken('t')
+    setActiveUser({ userId: 'bob', via: 'passkey' })
+    expect(isAuthenticated()).toBe(true)
+    logout()
+    expect(getToken()).toBeNull()
+    expect(getActiveUser()).toBeNull()
+    expect(isAuthenticated()).toBe(false)
+  })
+})

web/src/auth/session.ts

@@ -1,25 +1,50 @@
-// Session token is kept in memory only — NEVER localStorage/sessionStorage/URLs.
+// Session state is kept in memory only — NEVER localStorage/sessionStorage/URLs.
+// It holds (a) the bearer token and (b) the active demo user. Both are lost on a
+// full page refresh by design (in-memory only); this is acceptable for the trusted
+// demo environment and documented in the UI ("sign in again after refresh").
 // If the backend later moves to HTTP-only cookies, `credentials: 'include'` on the
-// client already carries them and this module becomes a no-op.
+// client already carries them and the token half of this module becomes a no-op.
+
+export interface ActiveUser {
+  userId: string
+  via: 'demo' | 'passkey'
+}
 
 let token: string | null = null
+let activeUser: ActiveUser | null = null
 const listeners = new Set<() => void>()
 
+function emit(): void {
+  listeners.forEach((fn) => fn())
+}
+
 export function setToken(t: string | null): void {
   token = t
-  listeners.forEach((fn) => fn())
+  emit()
 }
 
 export function getToken(): string | null {
   return token
 }
 
+export function setActiveUser(user: ActiveUser | null): void {
+  activeUser = user
+  emit()
+}
+
+export function getActiveUser(): ActiveUser | null {
+  return activeUser
+}
+
 export function isAuthenticated(): boolean {
   return token !== null
 }
 
+/** Clears both the token and the active user. */
 export function logout(): void {
-  setToken(null)
+  token = null
+  activeUser = null
+  emit()
 }
 
 export function onSessionChange(fn: () => void): () => void {

web/src/components/AppFooter.tsx

@@ -0,0 +1,52 @@
+import { useEffect, useState } from 'react'
+import { getVersion } from '../api/version'
+import { getProviders } from '../api/payments'
+import { useI18n } from '../i18n'
+import type { ProvidersResponse, VersionInfo } from '../types'
+
+/** Non-intrusive footer: environment facts (from /payments/providers) + a version
+ *  line (from /version) so the deployed build is verifiable. No secrets are shown. */
+export function AppFooter() {
+  const { t } = useI18n()
+  const [version, setVersion] = useState<VersionInfo | null>(null)
+  const [providers, setProviders] = useState<ProvidersResponse | null>(null)
+
+  useEffect(() => {
+    let live = true
+    getVersion().then((v) => live && setVersion(v)).catch(() => {})
+    getProviders().then((p) => live && setProviders(p)).catch(() => {})
+    return () => {
+      live = false
+    }
+  }, [])
+
+  const d = providers?.default
+  return (
+    <footer className="app-footer">
+      <details className="env-panel">
+        <summary>{t('env.title')}</summary>
+        <dl className="env-grid">
+          <dt>{t('env.country')}</dt>
+          <dd>{t('env.countryValue')}</dd>
+          <dt>{t('env.currency')}</dt>
+          <dd className="mono">{d?.currency ?? 'SAR'}</dd>
+          <dt>{t('env.timezone')}</dt>
+          <dd className="mono">{d?.timezone ?? 'Asia/Riyadh'}</dd>
+          <dt>{t('env.languages')}</dt>
+          <dd>{t('env.languagesValue')}</dd>
+          <dt>{t('env.provider')}</dt>
+          <dd>{version?.provider_mode === 'mock' || !version ? t('env.providerValue') : version.provider_mode}</dd>
+          <dt>{t('env.mode')}</dt>
+          <dd>{t('env.modeValue')}</dd>
+          <dt>{t('env.realMoney')}</dt>
+          <dd>{t('env.no')}</dd>
+        </dl>
+      </details>
+      <p className="version-line mono" dir="ltr">
+        {version
+          ? `${t('version.prefix')}${version.app_version} · ${version.commit} · ${version.ui_mode} · ${version.provider_mode}`
+          : t('version.unknown')}
+      </p>
+    </footer>
+  )
+}

web/src/hooks/useSession.ts

@@ -1,8 +1,24 @@
 import { useEffect, useState } from 'react'
-import { getToken, isAuthenticated, onSessionChange } from '../auth/session'
+import { getActiveUser, getToken, isAuthenticated, onSessionChange, type ActiveUser } from '../auth/session'
 
-export function useSession() {
-  const [authed, setAuthed] = useState(isAuthenticated())
-  useEffect(() => onSessionChange(() => setAuthed(isAuthenticated())), [])
-  return { authed, token: getToken() }
+interface SessionState {
+  authed: boolean
+  token: string | null
+  activeUser: ActiveUser | null
+}
+
+export function useSession(): SessionState {
+  const [state, setState] = useState<SessionState>(() => ({
+    authed: isAuthenticated(),
+    token: getToken(),
+    activeUser: getActiveUser(),
+  }))
+  useEffect(
+    () =>
+      onSessionChange(() =>
+        setState({ authed: isAuthenticated(), token: getToken(), activeUser: getActiveUser() }),
+      ),
+    [],
+  )
+  return state
 }

web/src/i18n/ar.ts

@@ -3,33 +3,57 @@ import type { MessageKey } from './en'
 export const ar: Record<MessageKey, string> = {
   'app.title': 'أمان باي',
   'app.tagline': 'بصمتك الحيوية هي بطاقتك',
+  'demo.banner': 'بيئة تجريبية موثوقة — مدفوعات وهمية، لا تُحرّك أموالًا حقيقية.',
   'nav.pay': 'الدفع',
   'nav.enroll': 'التسجيل',
   'lang.toggle': 'English',
-  'enroll.title': 'التسجيل / تسجيل الدخول',
+
+  'header.activeUser': 'مُسجّل الدخول: {user}',
+  'header.noUser': 'غير مُسجّل الدخول',
+
+  // ---- Enroll / auth ----
+  'enroll.title': 'التسجيل وتسجيل الدخول',
   'enroll.userId': 'معرّف المستخدم',
+  'enroll.needUserId': 'أدخل معرّف المستخدم أولًا.',
+  'enroll.sectionDemo': 'هوية تجريبية',
   'enroll.demo': 'تحميل هوية تجريبية',
-  'enroll.passkey': 'إضافة بصمة الجهاز / Face ID',
-  'enroll.passkeyOk': 'تم تسجيل بصمة الجهاز',
-  'enroll.passkeyCancelled': 'أُلغيت — حاول مرة أخرى أو استخدم جهازًا آخر',
-  'enroll.passkeyUnsupported': 'لا يوجد مستشعر حيوي متاح على هذا الجهاز/المتصفح',
-  'enroll.loggedInAs': 'مُسجّل الدخول باسم {user}',
+  'enroll.demoHint': 'يُسجّل البصمات الحيوية التجريبية لهذا المعرّف ويُدخلك.',
+  'enroll.sectionPasskey': 'مفتاح مرور الجهاز',
+  'enroll.registerPasskey': 'تسجيل مفتاح مرور',
+  'enroll.signInPasskey': 'الدخول بمفتاح المرور',
+  'enroll.passkeyHint': 'يستخدم بصمة الجهاز / Face ID عبر WebAuthn.',
+  'enroll.passkeyOk': 'تم تسجيل مفتاح المرور على هذا الجهاز.',
+  'enroll.signedIn': 'مُسجّل الدخول باسم {user}.',
+  'enroll.signedOut': 'تم تسجيل الخروج.',
+  'enroll.passkeyCancelled': 'أُلغيت — حاول مرة أخرى أو استخدم جهازًا آخر.',
+  'enroll.passkeyUnsupported': 'لا يوجد مستشعر حيوي متاح على هذا الجهاز/المتصفح.',
   'auth.logout': 'تسجيل الخروج',
+
+  // ---- Pay ----
   'pay.title': 'الدفع — بدون بطاقة',
   'pay.amount': 'المبلغ (ريال)',
   'pay.merchant': 'التاجر',
   'pay.iban': 'آيبان المستفيد',
+  'pay.description': 'مرجع (اختياري)',
   'pay.submit': 'ادفع',
   'pay.submitting': 'جارٍ الإرسال…',
-  'pay.needLogin': 'سجّل الدخول أولًا (تبويب التسجيل).',
-  'pay.customerAction': 'يحتاج بنكك إلى الموافقة على هذه العملية.',
-  'pay.openBank': 'فتح موافقة البنك',
-  'pay.simulateSettle': 'محاكاة التسوية (تجريبي)',
-  'pay.processing': 'قيد المعالجة — لم تكتمل بعد',
+  'pay.needLogin': 'سجّل الدخول من تبويب التسجيل للدفع.',
+  'pay.payingAs': 'الدفع باسم {user}',
+  'pay.summary': 'ملخّص العملية',
+  'pay.customerAction': 'مطلوب موافقة البنك لإكمال هذه العملية.',
+  'pay.mockBankInfo': 'هذه خطوة موافقة بنكية محاكاة — لا يتم الاتصال ببنك حقيقي.',
+  'pay.openBank': 'المتابعة إلى البنك',
+  'pay.simulateSettle': 'محاكاة موافقة البنك',
+  'pay.processing': 'قيد المعالجة — لم تكتمل بعد.',
   'pay.newPayment': 'عملية دفع جديدة',
+  'pay.cancel': 'إلغاء العملية',
+  'pay.original': 'الأصلي',
+  'pay.refundedAmount': 'المُسترد',
+  'pay.remaining': 'المتبقّي',
   'pay.refunded': 'تم استرداد {amount}',
-  'pay.correlation': 'معرّف الربط',
-  'pay.requestId': 'معرّف الطلب',
+  'pay.succeeded': 'تمت العملية بنجاح.',
+
+  // ---- Status labels ----
   'status.created': 'أُنشئت',
   'status.requires_customer_action': 'بانتظار بنكك',
   'status.authorizing': 'جارٍ التفويض',
@@ -40,6 +64,83 @@ export const ar: Record<MessageKey, string> = {
   'status.partially_refunded': 'مُستردة جزئيًا',
   'status.refunded': 'مُستردة',
   'status.expired': 'منتهية',
+
+  // ---- Status explanations ----
+  'statusHelp.created': 'تم إنشاء طلب الدفع.',
+  'statusHelp.requires_customer_action': 'أكّد العملية عبر خطوة البنك المحاكاة.',
+  'statusHelp.authorizing': 'يجري التحقّق من تفويض العميل.',
+  'statusHelp.processing': 'جارٍ تنفيذ التحويل — لا تعتبرها ناجحة بعد.',
+  'statusHelp.succeeded': 'تمت العملية بنجاح.',
+  'statusHelp.failed': 'رُفضت العملية أو تعذّر إكمالها.',
+  'statusHelp.cancelled': 'أُلغيت العملية.',
+  'statusHelp.partially_refunded': 'تم استرداد جزء ��ن العملية.',
+  'statusHelp.refunded': 'تم استرداد كامل المبلغ.',
+  'statusHelp.expired': 'انتهت مهلة التفويض.',
+
+  // ---- Demo scenario selector ----
+  'scenario.title': 'سيناريوهات تجريبية (محاكاة)',
+  'scenario.hint': 'يُشغّل نواة الدفع الحقيقية عبر المزوّد الوهمي. حالة الخادم هي المرجع.',
+  'scenario.approve': 'الموافقة والتسوية',
+  'scenario.decline': 'الرفض',
+  'scenario.expire': 'انتهاء المهلة',
+  'scenario.cancelProvider': 'الإلغاء عبر المزوّد',
+  'scenario.authorizing': 'الانتقال إلى التفويض',
+  'scenario.processing': 'الانتقال إلى المعالجة',
+  'scenario.partialRefund': 'محاكاة استرداد جزئي',
+  'scenario.fullRefund': 'محاكاة استرداد كامل',
+
+  // ---- Environment panel ----
+  'env.title': 'البيئة',
+  'env.country': 'الدولة',
+  'env.countryValue': 'المملكة العربية السعودية',
+  'env.currency': 'العملة',
+  'env.timezone': 'المنطقة الزمنية',
+  'env.languages': 'اللغات',
+  'env.languagesValue': 'العربية، الإنجليزية',
+  'env.provider': 'المزوّد',
+  'env.providerValue': 'وهمي',
+  'env.mode': 'الوضع',
+  'env.modeValue': 'غير حافظ للأموال',
+  'env.realMoney': 'تحويل أموال حقيقية',
+  'env.no': 'لا',
+
+  // ---- Version footer ----
+  'version.prefix': 'إصدار ',
+  'version.unknown': 'الإصدار غير متاح',
+
+  // ---- Not found ----
+  'notFound.title': 'الصفحة غير موجودة',
+  'notFound.body': 'هذا المسار غير موجود.',
+  'notFound.goPay': 'الذهاب إلى الدفع',
+  'notFound.goEnroll': 'الذهاب إلى التسجيل',
+
+  // ---- Technical / support details ----
+  'tech.title': 'تفاصيل تقنية / للدعم',
+  'tech.paymentId': 'معرّف العملية',
+  'tech.providerRef': 'مرجع المزوّد',
+  'tech.correlationId': 'معرّف الربط',
+  'tech.requestId': 'معرّف الطلب',
+  'tech.created': 'أُنشئت',
+  'tech.updated': 'آخر تحديث',
+
+  // ---- Errors ----
   'error.generic': 'حدث خطأ ما. حاول مرة أخرى.',
   'error.network': 'مشكلة في الشبكة — تحقّق من اتصالك.',
+  'error.timeout': 'انتهت مهلة الطلب — حاول مرة أخرى.',
+  'error.withRef': '{msg} (المرجع: {id})',
+  'error.amountEmpty': 'أدخل المبلغ.',
+  'error.amountInvalid': 'أدخل مبلغًا صحيحًا (خانتان عشريتان كحدّ أقصى).',
+  'error.amountZero': 'يجب أن يكون المبلغ أكبر من صفر.',
+  'error.amountNegative': 'يجب أن يكون المبلغ موجبًا.',
+  'error.amountTooLarge': 'المبلغ كبير جدًا لهذه البيئة التجريبية.',
+  'error.ibanInvalid': 'أدخل آيبان سعودي صحيح (SA ثم 22 رقمًا).',
+  'error.merchantEmpty': 'أدخل اسم التاجر.',
+  'error.payeeEmpty': 'أدخل آيبان المستفيد.',
+  'error.duplicate': 'تم إرسال هذه العملية مسبقًا.',
+  'error.noActiveUser': 'سجّل الدخول من تبويب التسجيل أولًا.',
+  'error.paymentCreate': 'تعذّر إنشاء العملية.',
+  'error.cancel': 'تعذّر إلغاء العملية.',
+  'error.refund': 'تعذّر تنفيذ الاسترداد.',
+  'error.passkeyRegister': 'فشل تسجيل مفتاح المرور.',
+  'error.passkeySignin': 'فشل الدخول بمفتاح المرور.',
 }

web/src/i18n/en.ts

@@ -1,33 +1,57 @@
 export const en = {
   'app.title': 'AmanPay',
   'app.tagline': 'Your biometrics are your card',
+  'demo.banner': 'Trusted demo — mock payments, no real money moves.',
   'nav.pay': 'Pay',
   'nav.enroll': 'Enroll',
   'lang.toggle': 'العربية',
-  'enroll.title': 'Register / Sign in',
+
+  'header.activeUser': 'Signed in: {user}',
+  'header.noUser': 'Not signed in',
+
+  // ---- Enroll / auth ----
+  'enroll.title': 'Enroll & sign in',
   'enroll.userId': 'User ID',
+  'enroll.needUserId': 'Enter a user ID first.',
+  'enroll.sectionDemo': 'Demo identity',
   'enroll.demo': 'Load demo identity',
-  'enroll.passkey': 'Add device fingerprint / Face ID',
-  'enroll.passkeyOk': 'Device biometric registered',
-  'enroll.passkeyCancelled': 'Cancelled — try again or use another device',
-  'enroll.passkeyUnsupported': 'This device/browser has no usable biometric sensor',
-  'enroll.loggedInAs': 'Signed in as {user}',
+  'enroll.demoHint': 'Enrolls the bundled demo biometrics for this user ID and signs you in.',
+  'enroll.sectionPasskey': 'Device passkey',
+  'enroll.registerPasskey': 'Register a passkey',
+  'enroll.signInPasskey': 'Sign in with passkey',
+  'enroll.passkeyHint': 'Uses your device fingerprint / Face ID (WebAuthn).',
+  'enroll.passkeyOk': 'Passkey registered on this device.',
+  'enroll.signedIn': 'Signed in as {user}.',
+  'enroll.signedOut': 'Signed out.',
+  'enroll.passkeyCancelled': 'Cancelled — try again or use another device.',
+  'enroll.passkeyUnsupported': 'This device/browser has no usable biometric sensor.',
   'auth.logout': 'Sign out',
+
+  // ---- Pay ----
   'pay.title': 'Pay — cardless',
   'pay.amount': 'Amount (SAR)',
   'pay.merchant': 'Merchant',
   'pay.iban': 'Payee IBAN',
+  'pay.description': 'Reference (optional)',
   'pay.submit': 'Pay',
   'pay.submitting': 'Submitting…',
-  'pay.needLogin': 'Sign in first (Enroll tab).',
-  'pay.customerAction': 'Your bank needs to authorize this payment.',
-  'pay.openBank': 'Open bank authorization',
-  'pay.simulateSettle': 'Simulate settlement (mock)',
-  'pay.processing': 'Processing — not yet complete',
+  'pay.needLogin': 'Sign in on the Enroll tab to pay.',
+  'pay.payingAs': 'Paying as {user}',
+  'pay.summary': 'Payment summary',
+  'pay.customerAction': 'Bank authorization is required to complete this payment.',
+  'pay.mockBankInfo': 'This is a simulated bank-authorization step — no real bank is contacted.',
+  'pay.openBank': 'Continue to bank',
+  'pay.simulateSettle': 'Simulate bank approval',
+  'pay.processing': 'Processing — not yet complete.',
   'pay.newPayment': 'New payment',
+  'pay.cancel': 'Cancel payment',
+  'pay.original': 'Original',
+  'pay.refundedAmount': 'Refunded',
+  'pay.remaining': 'Remaining',
   'pay.refunded': 'Refunded {amount}',
-  'pay.correlation': 'Correlation ID',
-  'pay.requestId': 'Request ID',
+  'pay.succeeded': 'Payment completed successfully.',
+
+  // ---- Status labels ----
   'status.created': 'Created',
   'status.requires_customer_action': 'Awaiting your bank',
   'status.authorizing': 'Authorizing',
@@ -38,8 +62,85 @@ export const en = {
   'status.partially_refunded': 'Partially refunded',
   'status.refunded': 'Refunded',
   'status.expired': 'Expired',
+
+  // ---- Status explanations ----
+  'statusHelp.created': 'Payment request created.',
+  'statusHelp.requires_customer_action': 'Confirm the payment through the simulated bank action.',
+  'statusHelp.authorizing': 'Customer authorization is being verified.',
+  'statusHelp.processing': 'The transfer is processing — do not treat it as successful yet.',
+  'statusHelp.succeeded': 'Payment completed successfully.',
+  'statusHelp.failed': 'Payment was declined or could not be completed.',
+  'statusHelp.cancelled': 'Payment was cancelled.',
+  'statusHelp.partially_refunded': 'Part of the payment was refunded.',
+  'statusHelp.refunded': 'The payment was fully refunded.',
+  'statusHelp.expired': 'The authorization window expired.',
+
+  // ---- Demo scenario selector ----
+  'scenario.title': 'Demo scenarios (simulation)',
+  'scenario.hint': 'Drives the real Payment Core via the mock provider. Backend status is authoritative.',
+  'scenario.approve': 'Approve & settle',
+  'scenario.decline': 'Decline',
+  'scenario.expire': 'Expire',
+  'scenario.cancelProvider': 'Cancel via provider',
+  'scenario.authorizing': 'Move to authorizing',
+  'scenario.processing': 'Move to processing',
+  'scenario.partialRefund': 'Simulate partial refund',
+  'scenario.fullRefund': 'Simulate full refund',
+
+  // ---- Environment panel ----
+  'env.title': 'Environment',
+  'env.country': 'Country',
+  'env.countryValue': 'Saudi Arabia',
+  'env.currency': 'Currency',
+  'env.timezone': 'Time zone',
+  'env.languages': 'Languages',
+  'env.languagesValue': 'Arabic, English',
+  'env.provider': 'Provider',
+  'env.providerValue': 'Mock',
+  'env.mode': 'Mode',
+  'env.modeValue': 'Non-custodial',
+  'env.realMoney': 'Real money moved',
+  'env.no': 'No',
+
+  // ---- Version footer ----
+  'version.prefix': 'v',
+  'version.unknown': 'version unavailable',
+
+  // ---- Not found ----
+  'notFound.title': 'Page not found',
+  'notFound.body': "That route doesn't exist.",
+  'notFound.goPay': 'Go to Pay',
+  'notFound.goEnroll': 'Go to Enroll',
+
+  // ---- Technical / support details ----
+  'tech.title': 'Technical / support details',
+  'tech.paymentId': 'Payment ID',
+  'tech.providerRef': 'Provider reference',
+  'tech.correlationId': 'Correlation ID',
+  'tech.requestId': 'Request ID',
+  'tech.created': 'Created',
+  'tech.updated': 'Updated',
+
+  // ---- Errors ----
   'error.generic': 'Something went wrong. Please try again.',
   'error.network': 'Network problem — check your connection.',
+  'error.timeout': 'The request timed out — please try again.',
+  'error.withRef': '{msg} (ref: {id})',
+  'error.amountEmpty': 'Enter an amount.',
+  'error.amountInvalid': 'Enter a valid amount (up to 2 decimals).',
+  'error.amountZero': 'Amount must be greater than zero.',
+  'error.amountNegative': 'Amount must be positive.',
+  'error.amountTooLarge': 'Amount is too large for this demo.',
+  'error.ibanInvalid': 'Enter a valid Saudi IBAN (SA + 22 digits).',
+  'error.merchantEmpty': 'Enter a merchant name.',
+  'error.payeeEmpty': 'Enter a payee IBAN.',
+  'error.duplicate': 'This payment was already submitted.',
+  'error.noActiveUser': 'Sign in on the Enroll tab first.',
+  'error.paymentCreate': 'Could not create the payment.',
+  'error.cancel': 'Could not cancel the payment.',
+  'error.refund': 'Could not process the refund.',
+  'error.passkeyRegister': 'Passkey registration failed.',
+  'error.passkeySignin': 'Passkey sign-in failed.',
 } as const
 
 export type MessageKey = keyof typeof en

web/src/i18n/i18n.test.tsx

@@ -1,6 +1,9 @@
 import { describe, it, expect } from 'vitest'
 import { render, screen } from '@testing-library/react'
 import { I18nProvider, useI18n } from './index'
+import { en } from './en'
+import { ar } from './ar'
+import { PAYMENT_STATUSES } from '../types'
 
 function Probe() {
   const { t, dir } = useI18n()
@@ -20,3 +23,28 @@ describe('i18n + RTL', () => {
     expect(screen.getByText('الدفع')).toBeInTheDocument()
   })
 })
+
+describe('i18n completeness', () => {
+  it('English and Arabic dictionaries have identical keys', () => {
+    const enKeys = Object.keys(en).sort()
+    const arKeys = Object.keys(ar).sort()
+    expect(arKeys).toEqual(enKeys)
+  })
+
+  it('every payment status has a label and an explanation in both locales', () => {
+    for (const s of PAYMENT_STATUSES) {
+      for (const dict of [en, ar] as const) {
+        expect(dict[`status.${s}` as keyof typeof dict]).toBeTruthy()
+        expect(dict[`statusHelp.${s}` as keyof typeof dict]).toBeTruthy()
+      }
+    }
+  })
+
+  it('runtime error messages are actually translated to Arabic (not English)', () => {
+    for (const k of ['error.network', 'error.timeout', 'error.paymentCreate', 'error.cancel',
+      'error.refund', 'error.passkeySignin', 'error.ibanInvalid'] as const) {
+      expect(ar[k]).toBeTruthy()
+      expect(ar[k]).not.toBe(en[k]) // genuinely localized, not an English fallback
+    }
+  })
+})

web/src/pages/EnrollPage.test.tsx

@@ -0,0 +1,39 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { render, screen, fireEvent, waitFor } from '@testing-library/react'
+import { I18nProvider } from '../i18n'
+import { EnrollPage } from './EnrollPage'
+import * as authApi from '../api/auth'
+import { logout } from '../auth/session'
+
+vi.mock('../api/auth')
+
+const renderEnroll = () => render(<I18nProvider initial="en"><EnrollPage /></I18nProvider>)
+
+describe('EnrollPage — separated auth actions', () => {
+  beforeEach(() => { vi.resetAllMocks(); logout() })
+
+  it('shows the demo, register-passkey and sign-in-passkey actions distinctly', () => {
+    renderEnroll()
+    expect(screen.getByRole('button', { name: 'Load demo identity' })).toBeInTheDocument()
+    expect(screen.getByRole('button', { name: 'Register a passkey' })).toBeInTheDocument()
+    expect(screen.getByRole('button', { name: 'Sign in with passkey' })).toBeInTheDocument()
+  })
+
+  it('Load demo identity calls demoSeed with the typed user id', async () => {
+    const seed = vi.spyOn(authApi, 'demoSeed').mockResolvedValue({ success: true, user_id: 'carol', modalities: [] })
+    renderEnroll()
+    const input = screen.getByLabelText('User ID')
+    fireEvent.change(input, { target: { value: 'carol' } })
+    fireEvent.click(screen.getByRole('button', { name: 'Load demo identity' }))
+    await waitFor(() => expect(seed).toHaveBeenCalledWith('carol'))
+    expect(await screen.findByText(/Signed in as carol/)).toBeInTheDocument()
+  })
+
+  it('Sign in with passkey calls authenticatePasskey (wired login)', async () => {
+    const auth = vi.spyOn(authApi, 'authenticatePasskey').mockResolvedValue(true)
+    renderEnroll()
+    fireEvent.change(screen.getByLabelText('User ID'), { target: { value: 'dave' } })
+    fireEvent.click(screen.getByRole('button', { name: 'Sign in with passkey' }))
+    await waitFor(() => expect(auth).toHaveBeenCalledWith('dave'))
+  })
+})

web/src/pages/EnrollPage.tsx

@@ -1,63 +1,107 @@
 import { useState } from 'react'
-import { demoSeed, registerPasskey } from '../api/auth'
+import { authenticatePasskey, demoSeed, registerPasskey } from '../api/auth'
 import { logout } from '../auth/session'
 import { PasskeyCancelled, PasskeyUnsupported, platformAuthenticatorAvailable } from '../auth/passkey'
 import { useSession } from '../hooks/useSession'
 import { useI18n } from '../i18n'
+import { localizeError } from '../utils/errors'
 import { Button, Field, Callout, Spinner } from '../components/ui'
-import { ApiRequestError } from '../api/client'
+
+type Busy = 'demo' | 'register' | 'signin' | null
+type Msg = { tone: 'ok' | 'bad' | 'info'; text: string } | null
 
 export function EnrollPage() {
   const { t } = useI18n()
-  const { authed } = useSession()
+  const { authed, activeUser } = useSession()
   const [userId, setUserId] = useState('alice')
-  const [busy, setBusy] = useState<string | null>(null)
-  const [msg, setMsg] = useState<{ tone: 'ok' | 'bad' | 'info'; text: string } | null>(null)
+  const [busy, setBusy] = useState<Busy>(null)
+  const [msg, setMsg] = useState<Msg>(null)
+
+  const uid = () => userId.trim()
 
   async function onDemo() {
+    if (!uid()) { setMsg({ tone: 'info', text: t('enroll.needUserId') }); return }
     setBusy('demo'); setMsg(null)
     try {
-      const r = await demoSeed(userId.trim() || 'alice')
-      setMsg({ tone: 'ok', text: t('enroll.loggedInAs', { user: r.user_id }) })
+      const r = await demoSeed(uid())
+      setMsg({ tone: 'ok', text: t('enroll.signedIn', { user: r.user_id }) })
     } catch (e) {
-      setMsg({ tone: 'bad', text: e instanceof ApiRequestError ? e.message : t('error.generic') })
+      setMsg({ tone: 'bad', text: localizeError(e, t, 'error.generic') })
     } finally {
       setBusy(null)
     }
   }
 
-  async function onPasskey() {
-    setBusy('passkey'); setMsg(null)
+  async function onRegister() {
+    if (!uid()) { setMsg({ tone: 'info', text: t('enroll.needUserId') }); return }
+    setBusy('register'); setMsg(null)
     try {
       if (!(await platformAuthenticatorAvailable())) {
-        setMsg({ tone: 'info', text: t('enroll.passkeyUnsupported') })
-        return
+        setMsg({ tone: 'info', text: t('enroll.passkeyUnsupported') }); return
       }
-      await registerPasskey(userId.trim() || 'alice')
+      await registerPasskey(uid())
       setMsg({ tone: 'ok', text: t('enroll.passkeyOk') })
     } catch (e) {
       if (e instanceof PasskeyUnsupported) setMsg({ tone: 'info', text: t('enroll.passkeyUnsupported') })
       else if (e instanceof PasskeyCancelled) setMsg({ tone: 'info', text: t('enroll.passkeyCancelled') })
-      else setMsg({ tone: 'bad', text: t('error.generic') })
+      else setMsg({ tone: 'bad', text: localizeError(e, t, 'error.passkeyRegister') })
     } finally {
       setBusy(null)
     }
   }
 
+  async function onSignIn() {
+    if (!uid()) { setMsg({ tone: 'info', text: t('enroll.needUserId') }); return }
+    setBusy('signin'); setMsg(null)
+    try {
+      await authenticatePasskey(uid())
+      setMsg({ tone: 'ok', text: t('enroll.signedIn', { user: uid() }) })
+    } catch (e) {
+      if (e instanceof PasskeyUnsupported) setMsg({ tone: 'info', text: t('enroll.passkeyUnsupported') })
+      else if (e instanceof PasskeyCancelled) setMsg({ tone: 'info', text: t('enroll.passkeyCancelled') })
+      else setMsg({ tone: 'bad', text: localizeError(e, t, 'error.passkeySignin') })
+    } finally {
+      setBusy(null)
+    }
+  }
+
+  function onSignOut() {
+    logout()
+    setMsg({ tone: 'info', text: t('enroll.signedOut') })
+  }
+
   return (
     <section className="card" aria-labelledby="enroll-h">
       <h2 id="enroll-h">{t('enroll.title')}</h2>
+
       <Field id="e_user" label={t('enroll.userId')} value={userId}
              onChange={(e) => setUserId(e.target.value)} autoComplete="username" />
-      <div className="row">
+
+      <fieldset className="action-group">
+        <legend>{t('enroll.sectionDemo')}</legend>
+        <p className="hint">{t('enroll.demoHint')}</p>
         <Button onClick={onDemo} disabled={busy !== null}>
           {busy === 'demo' ? <Spinner label={t('pay.submitting')} /> : t('enroll.demo')}
         </Button>
-        <Button onClick={onPasskey} disabled={busy !== null}>
-          {busy === 'passkey' ? <Spinner label={t('pay.submitting')} /> : t('enroll.passkey')}
-        </Button>
-        {authed && <Button onClick={() => { logout(); setMsg(null) }}>{t('auth.logout')}</Button>}
-      </div>
+      </fieldset>
+
+      <fieldset className="action-group">
+        <legend>{t('enroll.sectionPasskey')}</legend>
+        <p className="hint">{t('enroll.passkeyHint')}</p>
+        <div className="row">
+          <Button onClick={onRegister} disabled={busy !== null}>
+            {busy === 'register' ? <Spinner label={t('pay.submitting')} /> : t('enroll.registerPasskey')}
+          </Button>
+          <Button onClick={onSignIn} disabled={busy !== null}>
+            {busy === 'signin' ? <Spinner label={t('pay.submitting')} /> : t('enroll.signInPasskey')}
+          </Button>
+        </div>
+      </fieldset>
+
+      {(authed || activeUser) && (
+        <Button onClick={onSignOut} disabled={busy !== null}>{t('auth.logout')}</Button>
+      )}
+
       {msg && <Callout tone={msg.tone}>{msg.text}</Callout>}
     </section>
   )

web/src/pages/NotFoundPage.test.tsx

@@ -0,0 +1,14 @@
+import { describe, it, expect, vi } from 'vitest'
+import { render, screen, fireEvent } from '@testing-library/react'
+import { I18nProvider } from '../i18n'
+import { NotFoundPage } from './NotFoundPage'
+
+describe('NotFoundPage', () => {
+  it('renders a 404 with navigation back to Pay/Enroll', () => {
+    const onNav = vi.fn()
+    render(<I18nProvider initial="en"><NotFoundPage onNav={onNav} /></I18nProvider>)
+    expect(screen.getByText('Page not found')).toBeInTheDocument()
+    fireEvent.click(screen.getByRole('button', { name: 'Go to Pay' }))
+    expect(onNav).toHaveBeenCalledWith('pay')
+  })
+})

web/src/pages/NotFoundPage.tsx

@@ -0,0 +1,15 @@
+import { useI18n } from '../i18n'
+
+export function NotFoundPage({ onNav }: { onNav: (r: 'pay' | 'enroll') => void }) {
+  const { t } = useI18n()
+  return (
+    <section className="card" aria-labelledby="nf-h">
+      <h2 id="nf-h">{t('notFound.title')}</h2>
+      <p>{t('notFound.body')}</p>
+      <div className="row">
+        <button className="btn" onClick={() => onNav('pay')}>{t('notFound.goPay')}</button>
+        <button className="btn" onClick={() => onNav('enroll')}>{t('notFound.goEnroll')}</button>
+      </div>
+    </section>
+  )
+}

web/src/pages/PayPage.test.tsx

@@ -3,53 +3,110 @@ import { render, screen, fireEvent, waitFor } from '@testing-library/react'
 import { I18nProvider } from '../i18n'
 import { PayPage } from './PayPage'
 import * as payApi from '../api/payments'
-import { setToken } from '../auth/session'
+import { logout, setActiveUser } from '../auth/session'
 
 vi.mock('../api/payments')
 
 const HOSTILE = '<img src=x onerror="window.__xss=1">'
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
 function mkPayment(over: Partial<any> = {}): any {
   return {
-    id: 'p1', user_id: 'alice', status: 'succeeded', amount_minor: 15050, currency: 'SAR',
+    id: 'p1', user_id: 'bob', status: 'succeeded', amount_minor: 15050, currency: 'SAR',
     amount: '150.50 SAR', country: 'SA', merchant_id: 'm', provider: 'mock',
     provider_ref: 'mp_1', correlation_id: HOSTILE, consent_id: 'c', refunded_minor: 0,
     requires_action_url: null, locked: true, created_at: 0, updated_at: 0, ...over,
   }
 }
-const renderPay = () => render(<I18nProvider initial="en"><PayPage /></I18nProvider>)
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const CAPS: any = {
+  routing: { SA: { provider: 'mock', capabilities: {
+    name: 'mock', supports_cancel: true, supports_refund: true, supports_partial_refund: true,
+    countries: ['*'], currencies: ['SAR'], payment_initiation: true, sandbox: true,
+  } } },
+  default: { country: 'SA', currency: 'SAR', timezone: 'Asia/Riyadh', locales: ['ar', 'en'] },
+  non_custodial: true,
+}
+const renderPay = () => render(<I18nProvider initial="en"><PayPage onNavEnroll={() => {}} /></I18nProvider>)
 
 describe('PayPage', () => {
-  beforeEach(() => { vi.restoreAllMocks(); setToken('t'); (window as any).__xss = undefined })
+  beforeEach(() => {
+    vi.resetAllMocks() // clears call history AND implementations of the auto-mocked module
+    logout()
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    ;(window as any).__xss = undefined
+    vi.spyOn(payApi, 'getProviders').mockResolvedValue(CAPS)
+    vi.spyOn(payApi, 'getPayment').mockResolvedValue(mkPayment({ status: 'requires_customer_action' }))
+  })
+
+  it('blocks payment when no active user and directs to Enroll', () => {
+    renderPay()
+    expect(screen.getByText(/Sign in on the Enroll tab/i)).toBeInTheDocument()
+    expect(screen.getByRole('button', { name: 'Pay' })).toBeDisabled()
+  })
+
+  it('creates a payment using the ACTIVE user (never hard-coded alice)', async () => {
+    setActiveUser({ userId: 'bob', via: 'demo' })
+    const create = vi.spyOn(payApi, 'createPayment').mockResolvedValue(mkPayment({ status: 'requires_customer_action' }))
+    renderPay()
+    fireEvent.click(screen.getByRole('button', { name: 'Pay' }))
+    await waitFor(() => expect(create).toHaveBeenCalledTimes(1))
+    expect(create.mock.calls[0][0].userId).toBe('bob')
+    expect(create.mock.calls[0][0].userId).not.toBe('alice')
+  })
 
   it('prevents duplicate submission (one create per action)', async () => {
+    setActiveUser({ userId: 'bob', via: 'demo' })
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     let resolve: (v: any) => void = () => {}
     const create = vi.spyOn(payApi, 'createPayment').mockImplementation(
-      () => new Promise((r) => { resolve = r }),
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      () => new Promise<any>((r) => { resolve = r }),
     )
-    vi.spyOn(payApi, 'getPayment').mockResolvedValue(mkPayment({ status: 'requires_customer_action' }))
     renderPay()
     const btn = screen.getByRole('button', { name: 'Pay' })
     fireEvent.click(btn); fireEvent.click(btn); fireEvent.click(btn)
-    resolve(mkPayment({ status: 'requires_customer_action', requires_action_url: null }))
+    resolve(mkPayment({ status: 'requires_customer_action' }))
     await waitFor(() => expect(create).toHaveBeenCalledTimes(1))
   })
 
   it('renders hostile backend text as text, not HTML (XSS regression)', async () => {
+    setActiveUser({ userId: 'bob', via: 'demo' })
     vi.spyOn(payApi, 'createPayment').mockResolvedValue(mkPayment())
     vi.spyOn(payApi, 'getPayment').mockResolvedValue(mkPayment())
     const { container } = renderPay()
     fireEvent.click(screen.getByRole('button', { name: 'Pay' }))
     await waitFor(() => expect(screen.getByText('Succeeded')).toBeInTheDocument())
-    expect(container.querySelector('img')).toBeNull()      // no HTML injected
-    expect((window as any).__xss).toBeUndefined()          // handler never fired
+    expect(container.querySelector('img')).toBeNull()
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    expect((window as any).__xss).toBeUndefined()
   })
 
   it('distinguishes processing from success', async () => {
+    setActiveUser({ userId: 'bob', via: 'demo' })
     vi.spyOn(payApi, 'createPayment').mockResolvedValue(mkPayment({ status: 'processing' }))
     vi.spyOn(payApi, 'getPayment').mockResolvedValue(mkPayment({ status: 'processing' }))
     renderPay()
     fireEvent.click(screen.getByRole('button', { name: 'Pay' }))
-    await waitFor(() => expect(screen.getByText('Processing')).toBeInTheDocument())
-    expect(screen.queryByText('Succeeded')).toBeNull()
+    await waitFor(() => expect(screen.getAllByText('Processing').length).toBeGreaterThan(0))
+    expect(screen.queryByText('Payment completed successfully.')).toBeNull()
+  })
+
+  it('shows Cancel only in a cancellable state, not when succeeded', async () => {
+    setActiveUser({ userId: 'bob', via: 'demo' })
+    vi.spyOn(payApi, 'createPayment').mockResolvedValue(mkPayment({ status: 'requires_customer_action' }))
+    vi.spyOn(payApi, 'getPayment').mockResolvedValue(mkPayment({ status: 'requires_customer_action' }))
+    renderPay()
+    fireEvent.click(screen.getByRole('button', { name: 'Pay' }))
+    await waitFor(() => expect(screen.getByRole('button', { name: 'Cancel payment' })).toBeInTheDocument())
+  })
+
+  it('hides Cancel when terminal (succeeded)', async () => {
+    setActiveUser({ userId: 'bob', via: 'demo' })
+    vi.spyOn(payApi, 'createPayment').mockResolvedValue(mkPayment({ status: 'succeeded' }))
+    vi.spyOn(payApi, 'getPayment').mockResolvedValue(mkPayment({ status: 'succeeded' }))
+    renderPay()
+    fireEvent.click(screen.getByRole('button', { name: 'Pay' }))
+    await waitFor(() => expect(screen.getByText('Succeeded')).toBeInTheDocument())
+    expect(screen.queryByRole('button', { name: 'Cancel payment' })).toBeNull()
   })
 })

web/src/pages/PayPage.tsx

@@ -1,15 +1,22 @@
-import { useMemo, useRef, useState } from 'react'
-import { createPayment, mockAdvance } from '../api/payments'
+import { useEffect, useMemo, useRef, useState } from 'react'
+import {
+  cancelPayment, createPayment, getPayment, getProviders, mockAdvance, refundPayment,
+} from '../api/payments'
 import { usePaymentPolling } from '../payments/usePaymentPolling'
-import { isSuccess, isTerminal } from '../payments/status'
+import {
+  isCancellable, isRefundable, isSuccess, isTerminal, statusHelpKey,
+} from '../payments/status'
 import { formatMoney, toMinor } from '../payments/money'
 import { formatDateTime } from '../utils/format'
 import { isSafeExternalUrl } from '../utils/url'
+import { validateAmount, validateIban, validateMerchant } from '../utils/validate'
+import { localizeError } from '../utils/errors'
 import { useSession } from '../hooks/useSession'
 import { useI18n } from '../i18n'
 import { Button, Field, StatusBadge, Callout, Spinner } from '../components/ui'
-import { ApiRequestError, getLastRequestId } from '../api/client'
-import type { PaymentView } from '../types'
+import { getLastRequestId } from '../api/client'
+import type { MessageKey } from '../i18n/en'
+import type { PaymentView, ProviderCapabilities } from '../types'
 
 const DEMO_IBAN = 'SA0380000000608010167519'
 const ALLOWED_ACTION_HOSTS = ['mock-bank.example'] // real provider hosts added via config
@@ -20,59 +27,87 @@ function newIdemKey(): string {
     : `idem-${Date.now()}-${Math.random().toString(16).slice(2)}`
 }
 
-export function PayPage() {
+export function PayPage({ onNavEnroll }: { onNavEnroll: () => void }) {
   const { t, locale } = useI18n()
-  const { authed } = useSession()
+  const { activeUser } = useSession()
   const [amount, setAmount] = useState('150.50')
   const [merchant, setMerchant] = useState('Blue Bottle')
   const [iban, setIban] = useState(DEMO_IBAN)
+  const [reference, setReference] = useState('')
   const [created, setCreated] = useState<PaymentView | null>(null)
   const [submitting, setSubmitting] = useState(false)
+  const [busy, setBusy] = useState<string | null>(null)
   const [error, setError] = useState<string | null>(null)
-  // Idempotency key is generated once per user action and reused across retries.
+  const [caps, setCaps] = useState<ProviderCapabilities | null>(null)
+  const [mockActive, setMockActive] = useState(false)
   const idemRef = useRef<string>(newIdemKey())
   const submittingRef = useRef(false)
 
   const { payment: polled } = usePaymentPolling(created?.id ?? null)
-  const payment = polled ?? created
+  // Prefer whichever snapshot is newer so manual actions reflect immediately.
+  const payment = useMemo<PaymentView | null>(() => {
+    if (polled && created) return polled.updated_at >= created.updated_at ? polled : created
+    return polled ?? created
+  }, [polled, created])
 
-  const amountError = useMemo(() => {
-    const n = Number(amount)
-    return !Number.isFinite(n) || n <= 0 ? t('error.generic') : undefined
-  }, [amount, t])
+  useEffect(() => {
+    let live = true
+    getProviders().then((p) => {
+      if (!live) return
+      const sa = p.routing?.SA
+      setCaps(sa?.capabilities ?? null)
+      setMockActive(sa?.provider === 'mock')
+    }).catch(() => {})
+    return () => { live = false }
+  }, [])
+
+  const amountErr = useMemo(() => validateAmount(amount), [amount])
+  const merchantErr = useMemo(() => validateMerchant(merchant), [merchant])
+  const ibanErr = useMemo(() => validateIban(iban), [iban])
+  const formInvalid = !!(amountErr || merchantErr || ibanErr)
+  const err = (k?: MessageKey) => (k ? t(k) : undefined)
 
   async function onPay() {
     if (submittingRef.current || created) return // duplicate-submission guard
-    if (amountError) return
+    if (!activeUser) { setError(t('error.noActiveUser')); return }
+    if (formInvalid) return
     submittingRef.current = true
     setSubmitting(true)
     setError(null)
     try {
       const p = await createPayment({
-        userId: 'alice',
+        userId: activeUser.userId, // active user — never hard-coded
         amountMinor: toMinor(amount, 'SAR'),
-        merchantId: merchant.trim() || 'merchant',
+        merchantId: merchant.trim(),
         payeeIban: iban.trim(),
+        description: reference.trim(),
         country: 'SA',
         currency: 'SAR',
         idempotencyKey: idemRef.current, // same key on retry -> backend idempotency
       })
       setCreated(p)
     } catch (e) {
-      // Keep the idempotency key so a retry of THIS action is deduplicated server-side.
-      setError(e instanceof ApiRequestError ? e.message : t('error.generic'))
+      setError(localizeError(e, t, 'error.paymentCreate'))
     } finally {
       submittingRef.current = false
       setSubmitting(false)
     }
   }
 
-  async function onSimulateSettle() {
+  // Runs an action against the real backend, then refreshes to the authoritative status.
+  async function run(label: string, fn: () => Promise<unknown>, fallback: MessageKey) {
     if (!created) return
+    setBusy(label); setError(null)
     try {
-      await mockAdvance(created.id, 'SETTLED')
-    } catch {
-      setError(t('error.generic'))
+      const r = await fn()
+      const fresh = r && typeof r === 'object' && 'status' in r
+        ? (r as PaymentView)
+        : await getPayment(created.id)
+      setCreated(fresh)
+    } catch (e) {
+      setError(localizeError(e, t, fallback))
+    } finally {
+      setBusy(null)
     }
   }
 
@@ -84,21 +119,34 @@ export function PayPage() {
 
   const actionUrl = payment?.requires_action_url ?? null
   const actionUrlSafe = actionUrl ? isSafeExternalUrl(actionUrl, ALLOWED_ACTION_HOSTS) : false
+  const canCancel = payment && isCancellable(payment.status) && caps?.supports_cancel !== false
+  const canRefund = payment && isRefundable(payment.status) && caps?.supports_refund !== false
+  const remaining = payment ? payment.amount_minor - payment.refunded_minor : 0
+  const showScenarios = mockActive && payment && !isTerminal(payment.status)
 
   return (
     <section className="card" aria-labelledby="pay-h">
       <h2 id="pay-h">{t('pay.title')}</h2>
-      {!authed && <Callout tone="info">{t('pay.needLogin')}</Callout>}
+
+      {!activeUser && (
+        <Callout tone="info">
+          {t('pay.needLogin')}{' '}
+          <button className="link" onClick={onNavEnroll}>{t('nav.enroll')}</button>
+        </Callout>
+      )}
+      {activeUser && <p className="paying-as">{t('pay.payingAs', { user: activeUser.userId })}</p>}
 
       {!created && (
         <>
           <Field id="p_amt" label={t('pay.amount')} value={amount} inputMode="decimal"
-                 onChange={(e) => setAmount(e.target.value)} error={amountError} />
+                 onChange={(e) => setAmount(e.target.value)} error={err(amountErr)} />
           <Field id="p_merch" label={t('pay.merchant')} value={merchant}
-                 onChange={(e) => setMerchant(e.target.value)} />
+                 onChange={(e) => setMerchant(e.target.value)} error={err(merchantErr)} />
           <Field id="p_iban" label={t('pay.iban')} value={iban}
-                 onChange={(e) => setIban(e.target.value)} />
-          <Button onClick={onPay} disabled={!authed || submitting || !!amountError} aria-busy={submitting}>
+                 onChange={(e) => setIban(e.target.value)} error={err(ibanErr)} />
+          <Field id="p_ref" label={t('pay.description')} value={reference}
+                 onChange={(e) => setReference(e.target.value)} />
+          <Button onClick={onPay} disabled={!activeUser || submitting || formInvalid} aria-busy={submitting}>
             {submitting ? <Spinner label={t('pay.submitting')} /> : t('pay.submit')}
           </Button>
         </>
@@ -112,48 +160,105 @@ export function PayPage() {
             <strong>{formatMoney(payment.amount_minor, payment.currency, locale)}</strong>
             <StatusBadge status={payment.status} />
           </div>
+          <p className="status-help">{t(statusHelpKey(payment.status) as MessageKey)}</p>
 
+          {/* Payment summary */}
+          <dl className="summary-grid">
+            <dt>{t('pay.merchant')}</dt><dd>{merchant}</dd>
+            <dt>{t('pay.iban')}</dt><dd className="mono" dir="ltr">{iban}</dd>
+            {activeUser && (<><dt>{t('nav.enroll')}</dt><dd>{activeUser.userId}</dd></>)}
+          </dl>
+
+          {/* Customer-action (simulated bank authorization) */}
           {payment.status === 'requires_customer_action' && (
             <Callout tone="warn">
               <p>{t('pay.customerAction')}</p>
+              <p className="hint">{t('pay.mockBankInfo')}</p>
               <div className="row">
                 {actionUrlSafe && actionUrl && (
                   <a className="btn" href={actionUrl} target="_blank" rel="noopener noreferrer">
                     {t('pay.openBank')}
                   </a>
                 )}
-                <Button onClick={onSimulateSettle}>{t('pay.simulateSettle')}</Button>
+                <Button onClick={() => run('settle', () => mockAdvance(payment.id, 'SETTLED'), 'error.generic')}
+                        disabled={busy !== null}>
+                  {t('pay.simulateSettle')}
+                </Button>
               </div>
             </Callout>
           )}
 
           {(payment.status === 'processing' || payment.status === 'authorizing') && (
-            <Callout tone="warn">
-              <Spinner label={t('pay.processing')} />
-            </Callout>
+            <Callout tone="warn"><Spinner label={t('pay.processing')} /></Callout>
           )}
 
+          {isSuccess(payment.status) && <Callout tone="ok">{t('pay.succeeded')}</Callout>}
+
+          {/* Refund visibility */}
           {payment.refunded_minor > 0 && (
-            <Callout tone="info">
-              {t('pay.refunded', { amount: formatMoney(payment.refunded_minor, payment.currency, locale) })}
-            </Callout>
+            <dl className="summary-grid">
+              <dt>{t('pay.original')}</dt>
+              <dd>{formatMoney(payment.amount_minor, payment.currency, locale)}</dd>
+              <dt>{t('pay.refundedAmount')}</dt>
+              <dd>{formatMoney(payment.refunded_minor, payment.currency, locale)}</dd>
+              <dt>{t('pay.remaining')}</dt>
+              <dd>{formatMoney(remaining, payment.currency, locale)}</dd>
+            </dl>
+          )}
+
+          {/* Cancel — only when the state + provider allow it */}
+          {canCancel && (
+            <Button onClick={() => run('cancel', () => cancelPayment(payment.id), 'error.cancel')}
+                    disabled={busy !== null}>
+              {busy === 'cancel' ? <Spinner label={t('pay.submitting')} /> : t('pay.cancel')}
+            </Button>
           )}
 
-          {isSuccess(payment.status) && <Callout tone="ok">✓</Callout>}
+          {/* Demo refund actions — use the REAL Payment Core refund API */}
+          {canRefund && remaining > 0 && (
+            <div className="row">
+              <Button onClick={() => run('prefund', () => refundPayment(payment.id, Math.floor(remaining / 2), 'demo'), 'error.refund')}
+                      disabled={busy !== null}>
+                {t('scenario.partialRefund')}
+              </Button>
+              <Button onClick={() => run('frefund', () => refundPayment(payment.id, undefined, 'demo'), 'error.refund')}
+                      disabled={busy !== null}>
+                {t('scenario.fullRefund')}
+              </Button>
+            </div>
+          )}
+
+          {/* Demo scenario selector — mock provider only, real backend transitions */}
+          {showScenarios && (
+            <details className="scenario">
+              <summary>{t('scenario.title')}</summary>
+              <p className="hint">{t('scenario.hint')}</p>
+              <div className="row wrap">
+                <Button onClick={() => run('s', () => mockAdvance(payment.id, 'AUTH_IN_PROGRESS'), 'error.generic')} disabled={busy !== null}>{t('scenario.authorizing')}</Button>
+                <Button onClick={() => run('s', () => mockAdvance(payment.id, 'SETTLING'), 'error.generic')} disabled={busy !== null}>{t('scenario.processing')}</Button>
+                <Button onClick={() => run('s', () => mockAdvance(payment.id, 'SETTLED'), 'error.generic')} disabled={busy !== null}>{t('scenario.approve')}</Button>
+                <Button onClick={() => run('s', () => mockAdvance(payment.id, 'DECLINED'), 'error.generic')} disabled={busy !== null}>{t('scenario.decline')}</Button>
+                <Button onClick={() => run('s', () => mockAdvance(payment.id, 'TIMED_OUT'), 'error.generic')} disabled={busy !== null}>{t('scenario.expire')}</Button>
+                <Button onClick={() => run('s', () => mockAdvance(payment.id, 'VOIDED'), 'error.generic')} disabled={busy !== null}>{t('scenario.cancelProvider')}</Button>
+              </div>
+            </details>
+          )}
 
           {isTerminal(payment.status) && (
             <Button onClick={reset}>{t('pay.newPayment')}</Button>
           )}
 
+          {/* Technical / support details */}
           <details className="support">
-            <summary>{t('pay.requestId')}</summary>
-            <div className="mono">
-              {t('pay.correlation')}: {payment.correlation_id}
-              <br />
-              {t('pay.requestId')}: {getLastRequestId() ?? '—'}
-              <br />
-              {formatDateTime(payment.updated_at, locale)}
-            </div>
+            <summary>{t('tech.title')}</summary>
+            <dl className="tech-grid mono" dir="ltr">
+              <dt>{t('tech.paymentId')}</dt><dd>{payment.id}</dd>
+              <dt>{t('tech.providerRef')}</dt><dd>{payment.provider_ref ?? '—'}</dd>
+              <dt>{t('tech.correlationId')}</dt><dd>{payment.correlation_id}</dd>
+              <dt>{t('tech.requestId')}</dt><dd>{getLastRequestId() ?? '—'}</dd>
+              <dt>{t('tech.created')}</dt><dd>{formatDateTime(payment.created_at, locale)}</dd>
+              <dt>{t('tech.updated')}</dt><dd>{formatDateTime(payment.updated_at, locale)}</dd>
+            </dl>
           </details>
         </div>
       )}

web/src/payments/status.test.ts

@@ -1,5 +1,8 @@
 import { describe, it, expect } from 'vitest'
-import { isTerminal, isSuccess, statusTone } from './status'
+import {
+  isTerminal, isSuccess, statusTone, isCancellable, isRefundable, statusHelpKey,
+} from './status'
+import { PAYMENT_STATUSES } from '../types'
 
 describe('payment status presentation', () => {
   it('terminal states', () => {
@@ -17,4 +20,19 @@ describe('payment status presentation', () => {
     expect(statusTone('failed')).toBe('bad')
     expect(statusTone('processing')).toBe('warn')
   })
+  it('cancellable states mirror the backend (created/req-action/authorizing only)', () => {
+    for (const s of ['created', 'requires_customer_action', 'authorizing'] as const)
+      expect(isCancellable(s)).toBe(true)
+    for (const s of ['processing', 'succeeded', 'failed', 'cancelled', 'refunded', 'expired', 'partially_refunded'] as const)
+      expect(isCancellable(s)).toBe(false)
+  })
+  it('refundable states are succeeded / partially_refunded', () => {
+    expect(isRefundable('succeeded')).toBe(true)
+    expect(isRefundable('partially_refunded')).toBe(true)
+    expect(isRefundable('processing')).toBe(false)
+    expect(isRefundable('failed')).toBe(false)
+  })
+  it('every status has a help key', () => {
+    for (const s of PAYMENT_STATUSES) expect(statusHelpKey(s)).toBe(`statusHelp.${s}`)
+  })
 })

web/src/payments/status.ts

@@ -37,7 +37,28 @@ export function statusKey(status: PaymentStatus): string {
   return `status.${status}`
 }
 
+/** i18n key for a one-line explanation of the status (localized). */
+export function statusHelpKey(status: PaymentStatus): string {
+  return `statusHelp.${status}`
+}
+
 /** "processing" is distinct from "success" — never conflate them in the UI. */
 export function isSuccess(status: PaymentStatus): boolean {
   return status === 'succeeded'
 }
+
+// A payment is cancellable only from these states — mirrors the backend state
+// machine (status.py): created / requires_customer_action / authorizing can move to
+// `cancelled`; `processing` cannot. The UI additionally checks provider capability.
+const CANCELLABLE: ReadonlySet<PaymentStatus> = new Set<PaymentStatus>([
+  'created', 'requires_customer_action', 'authorizing',
+])
+
+export function isCancellable(status: PaymentStatus): boolean {
+  return CANCELLABLE.has(status)
+}
+
+/** Refundable states — mirrors the backend (succeeded / partially_refunded). */
+export function isRefundable(status: PaymentStatus): boolean {
+  return status === 'succeeded' || status === 'partially_refunded'
+}

web/src/styles.css

@@ -49,4 +49,46 @@ h2 { margin: 0 0 12px; font-size: 18px; }
 .spin { width: 14px; height: 14px; border: 2px solid var(--muted); border-top-color: transparent;
   border-radius: 50%; animation: sp .8s linear infinite; }
 @keyframes sp { to { transform: rotate(360deg); } }
-@media (max-width: 560px) { .app { padding: 10px; } .topbar { flex-wrap: wrap; } }
+
+/* Header active user + language */
+.topbar-right { display: flex; align-items: center; gap: 10px; }
+.active-user { font-size: 12.5px; color: var(--muted); max-width: 160px; overflow: hidden;
+  text-overflow: ellipsis; white-space: nowrap; }
+
+/* Demo banner */
+.demo-banner { margin: 10px 0 0; padding: 8px 12px; border-radius: 10px; font-size: 12.5px;
+  color: var(--warn); background: color-mix(in srgb, var(--warn) 12%, transparent);
+  border: 1px solid color-mix(in srgb, var(--warn) 40%, transparent); }
+
+/* Enroll action groups */
+.action-group { border: 1px solid var(--border); border-radius: 12px; padding: 12px 14px; margin: 12px 0; }
+.action-group legend { color: var(--text); font-weight: 600; font-size: 13.5px; padding: 0 6px; }
+.hint { color: var(--muted); font-size: 12.5px; margin: 2px 0 8px; }
+.paying-as { color: var(--muted); font-size: 13px; margin: 4px 0 10px; }
+.status-help { color: var(--muted); font-size: 13px; margin: 6px 0 10px; }
+
+/* Definition grids (summary / technical / environment) */
+.summary-grid, .tech-grid, .env-grid { display: grid; grid-template-columns: max-content 1fr;
+  gap: 4px 14px; margin: 10px 0; font-size: 13px; }
+.summary-grid dt, .tech-grid dt, .env-grid dt { color: var(--muted); }
+.summary-grid dd, .tech-grid dd, .env-grid dd { margin: 0; }
+
+/* Scenario selector */
+.scenario { margin-top: 12px; padding: 4px 0; }
+.scenario summary { cursor: pointer; color: var(--warn); font-size: 13px; }
+.row.wrap { flex-wrap: wrap; }
+
+/* Inline link button (e.g. "go to Enroll") */
+.link { background: none; border: none; color: var(--primary); text-decoration: underline;
+  cursor: pointer; font: inherit; padding: 0; }
+
+/* Footer */
+.app-footer { margin-top: 20px; padding-top: 12px; border-top: 1px solid var(--border); color: var(--muted); }
+.env-panel summary { cursor: pointer; font-size: 13px; }
+.version-line { font-size: 11.5px; color: var(--muted); margin-top: 8px; }
+
+@media (max-width: 560px) {
+  .app { padding: 10px; }
+  .topbar { flex-wrap: wrap; }
+  .active-user { max-width: 110px; }
+}

web/src/test/setup.ts

@@ -1 +1,7 @@
 import '@testing-library/jest-dom/vitest'
+import { afterEach } from 'vitest'
+import { cleanup } from '@testing-library/react'
+
+// Unmount React trees between tests so components (and their polling timers /
+// event handlers) from one test never leak into the next.
+afterEach(() => cleanup())

web/src/types/index.ts

@@ -42,10 +42,32 @@ export interface EnrollResponse {
   reason?: string
 }
 
+export interface ProviderCapabilities {
+  name: string
+  countries: string[]
+  currencies: string[]
+  supports_cancel: boolean
+  supports_refund: boolean
+  supports_partial_refund: boolean
+  payment_initiation: boolean
+  sandbox: boolean
+}
+
 export interface ProvidersResponse {
   default: { country: string; currency: string; timezone: string; locales: string[] }
   non_custodial: boolean
-  routing: Record<string, { provider: string; capabilities?: unknown; status?: string }>
+  routing: Record<string, { provider: string; capabilities?: ProviderCapabilities; status?: string }>
+}
+
+export interface VersionInfo {
+  app_version: string
+  commit: string
+  build_time: string | null
+  frontend: string
+  backend: string
+  ui_mode: 'react' | 'legacy'
+  provider_mode: string
+  non_custodial: boolean
 }
 
 export interface ApiError {

web/src/utils/errors.test.ts

@@ -0,0 +1,40 @@
+import { describe, it, expect } from 'vitest'
+import { localizeError } from './errors'
+import { ApiRequestError } from '../api/client'
+import type { MessageKey } from '../i18n/en'
+
+// Echo translator: returns the key (with vars) so we can assert which key was chosen.
+const t = ((key: MessageKey, vars?: Record<string, string | number>) =>
+  vars ? `${key}:${JSON.stringify(vars)}` : key) as (
+  key: MessageKey, vars?: Record<string, string | number>,
+) => string
+
+describe('localizeError', () => {
+  it('maps network error to error.network', () => {
+    const e = new ApiRequestError({ status: 0, message: 'network error' })
+    expect(localizeError(e, t, 'error.paymentCreate')).toBe('error.network')
+  })
+
+  it('maps timeout to error.timeout', () => {
+    const e = new ApiRequestError({ status: 0, message: 'request timed out' })
+    expect(localizeError(e, t, 'error.paymentCreate')).toBe('error.timeout')
+  })
+
+  it('uses localized fallback + request id, NOT raw backend text', () => {
+    const e = new ApiRequestError({ status: 422, message: 'cannot cancel a succeeded payment', requestId: 'req1' })
+    const out = localizeError(e, t, 'error.cancel')
+    expect(out).toContain('error.withRef')
+    expect(out).toContain('error.cancel')
+    expect(out).toContain('req1')
+    expect(out).not.toContain('cannot cancel') // raw backend text never shown
+  })
+
+  it('falls back to the operation key when no request id', () => {
+    const e = new ApiRequestError({ status: 500, message: 'boom' })
+    expect(localizeError(e, t, 'error.refund')).toBe('error.refund')
+  })
+
+  it('handles non-API errors with the fallback', () => {
+    expect(localizeError(new Error('x'), t, 'error.generic')).toBe('error.generic')
+  })
+})

web/src/utils/errors.ts

@@ -0,0 +1,19 @@
+import { ApiRequestError, getLastRequestId } from '../api/client'
+import type { MessageKey } from '../i18n/en'
+
+type Translate = (key: MessageKey, vars?: Record<string, string | number>) => string
+
+/** Turn any thrown error into a SAFE, localized message. We never render raw backend
+ *  exception text to the user. Network/timeout get dedicated messages; every other
+ *  failure shows a context-specific localized fallback plus the request ID (when known)
+ *  so support can trace it. `fallbackKey` is the operation-specific message key. */
+export function localizeError(e: unknown, t: Translate, fallbackKey: MessageKey): string {
+  if (e instanceof ApiRequestError) {
+    if (e.status === 0) {
+      return t(e.message === 'request timed out' ? 'error.timeout' : 'error.network')
+    }
+    const rid = e.requestId ?? getLastRequestId() ?? undefined
+    return rid ? t('error.withRef', { msg: t(fallbackKey), id: rid }) : t(fallbackKey)
+  }
+  return t(fallbackKey)
+}

web/src/utils/validate.test.ts

@@ -0,0 +1,31 @@
+import { describe, it, expect } from 'vitest'
+import { validateAmount, validateIban, isValidSaudiIban, validateMerchant } from './validate'
+
+describe('validateAmount', () => {
+  it('accepts a valid 2-decimal amount', () => expect(validateAmount('150.50')).toBeUndefined())
+  it('accepts an integer amount', () => expect(validateAmount('200')).toBeUndefined())
+  it('rejects empty', () => expect(validateAmount('')).toBe('error.amountEmpty'))
+  it('rejects zero', () => expect(validateAmount('0')).toBe('error.amountZero'))
+  it('rejects negative', () => expect(validateAmount('-5')).toBe('error.amountInvalid'))
+  it('rejects non-numeric', () => expect(validateAmount('abc')).toBe('error.amountInvalid'))
+  it('rejects >2 decimals', () => expect(validateAmount('1.234')).toBe('error.amountInvalid'))
+  it('rejects too large', () => expect(validateAmount('2000000')).toBe('error.amountTooLarge'))
+  it('rejects lone dot', () => expect(validateAmount('.')).toBe('error.amountInvalid'))
+})
+
+describe('Saudi IBAN', () => {
+  const VALID = 'SA0380000000608010167519'
+  it('accepts a valid Saudi IBAN', () => expect(isValidSaudiIban(VALID)).toBe(true))
+  it('accepts with spaces', () => expect(isValidSaudiIban('SA03 8000 0000 6080 1016 7519')).toBe(true))
+  it('rejects wrong checksum', () => expect(isValidSaudiIban('SA0380000000608010167518')).toBe(false))
+  it('rejects wrong country', () => expect(isValidSaudiIban('GB0380000000608010167519')).toBe(false))
+  it('rejects short', () => expect(isValidSaudiIban('SA038000')).toBe(false))
+  it('validateIban maps invalid -> key', () => expect(validateIban('SA00')).toBe('error.ibanInvalid'))
+  it('validateIban maps empty -> key', () => expect(validateIban('')).toBe('error.payeeEmpty'))
+  it('validateIban passes valid', () => expect(validateIban(VALID)).toBeUndefined())
+})
+
+describe('validateMerchant', () => {
+  it('rejects empty', () => expect(validateMerchant('   ')).toBe('error.merchantEmpty'))
+  it('accepts text', () => expect(validateMerchant('Blue Bottle')).toBeUndefined())
+})

web/src/utils/validate.ts

@@ -0,0 +1,39 @@
+import type { MessageKey } from '../i18n/en'
+
+const MAX_MAJOR = 1_000_000 // demo ceiling; backend enforces its own limits
+
+/** Validate a SAR major-unit amount string. Returns an i18n error key or undefined. */
+export function validateAmount(raw: string): MessageKey | undefined {
+  const s = raw.trim()
+  if (!s) return 'error.amountEmpty'
+  if (!/^\d*\.?\d*$/.test(s) || s === '.') return 'error.amountInvalid'
+  const n = Number(s)
+  if (!Number.isFinite(n)) return 'error.amountInvalid'
+  if (n < 0) return 'error.amountNegative'
+  if (n === 0) return 'error.amountZero'
+  if (n > MAX_MAJOR) return 'error.amountTooLarge'
+  if (!/^\d+(\.\d{1,2})?$/.test(s)) return 'error.amountInvalid' // SAR = 2 decimals max
+  return undefined
+}
+
+/** Saudi IBAN: "SA" + 22 digits (24 chars), ISO 13616 mod-97 check == 1. */
+export function isValidSaudiIban(raw: string): boolean {
+  const s = raw.replace(/\s+/g, '').toUpperCase()
+  if (!/^SA\d{22}$/.test(s)) return false
+  const rearranged = s.slice(4) + s.slice(0, 4)
+  let rem = 0
+  for (const ch of rearranged) {
+    const val = ch >= 'A' && ch <= 'Z' ? String(ch.charCodeAt(0) - 55) : ch
+    for (const d of val) rem = (rem * 10 + (d.charCodeAt(0) - 48)) % 97
+  }
+  return rem === 1
+}
+
+export function validateIban(raw: string): MessageKey | undefined {
+  if (!raw.trim()) return 'error.payeeEmpty'
+  return isValidSaudiIban(raw) ? undefined : 'error.ibanInvalid'
+}
+
+export function validateMerchant(raw: string): MessageKey | undefined {
+  return raw.trim() ? undefined : 'error.merchantEmpty'
+}