09 — User Behaviour (Payments)
- Expected behaviour
- Common mistakes
- Fast paths
- Power users
- New users
- Expert users
- Accessibility users
- Interrupted sessions & retries
- Abandonment
- Frustration points + fixes
Expected behaviour, mistakes, fast paths, and how the UX resolves them.
Expected behaviour
- Accountant records a counter payment in < 60 s and sees a receipt instantly.
- Refunds are deliberate: reason required, exact amount shown, confirmation.
- Gateway outcomes surfaced as PENDING/PROCESSING/COMPLETED/FAILED, reconciled by the accountant, not auto-patched by clients.
- Invoice due amounts always reflect latest
paidAmount(pull-to-refresh).
Common mistakes
| Mistake | UX mitigation |
|---|---|
| Wrong payer selected | Payer search prefilled from invoice; editable before submit; detail shows full payer context |
| Wrong amount | Decimal formatter + min 0 + server validation; no silent rounding |
| Double-tap Submit → double payment | Submit disabled while pending; but no idempotency key server-side — flag OQ |
| Refunding too much | Client max = amount − refundedAmount; server 409 backstop |
| Recording gateway payment without gateway reference | Optional field lent; reconcile path exists |
| Reconciling with wrong status string | Radio limits choices; server maps unknown → pending |
Fast paths
- Invoice detail → "Record payment" prefills amount + payer.
- FAB from list → new payment.
- Recent payment repeated → copy previous (payer + description)
(proposed).
Power users
- Keyboard-first desktop:
/focus, Enter submit, ESC cancel, tab order fixed. - Keyboard shortcuts:
Nnew payment;Ctrl/Cmd+Ffilter.
New users
- First-time empty state explains "record your first payment"; help text on refund sheet explains guards.
Expert users
- Reconcile screen aggregates PENDING payments count; bulk-eligible design
(proposed)— today one PATCH per payment.
Accessibility users
- Money values spoken fully; statuses icon+label; focus order logical; large type reflows (no fixed heights).
Interrupted sessions & retries
- Interrupted mid-submit: button pending until server responds; on failure keep form intact; never half-write locally.
- Retries: exponential backoff for 5xx/network; 429 → countdown, no auto-retry.
Abandonment
- Close form → confirm discard (if touched); refund sheet discard without warning (non-destructive until submit).
Frustration points + fixes
| Frustration | Fix |
|---|---|
| "Where did my payment go?" | Traceable: payment → invoice → receipt links; search |
| Invoice status stale after payment | Auto-link to invoice updates PAID/PARTIAL; pull-to-refresh |
| Can't fix a wrong gateway outcome | Reconcile screen sets status explicitly |
| Money precision doubt | Tabular figures + 2-decimal format; show refundedAmount explicitly |
| Two payment modules confusing (fees payments vs payments_v2) | Cross-module inconsistency flagged OQ-1 (see 12); UI shows canonical payments module records |
| 404 instead of validation on business rule | Client pre-validates marks/amounts; 404s handled as not-found UI when weird codes arrive—log + report |