[Gap-Audit] 040 Payment Retry UI: idempotency-key reuse, retry counter + cooling, error categorization, offline banner, audit log

[TortoiseWolfe]

Status correction (2026-04-27)

The original framing of this issue ("build /payment/result page + retry surface + offline error banner") was wrong. The route already exists.

src/app/payment-result/page.tsx shipped in commit ffb33a1 on 2026-04-16 — a 290-LOC, 6-state page with auth gating, suspense, real-time updates via usePaymentRealtime, and a working retry button. The 2026-04-25 audit cross-referenced spec text against documented status rather than the filesystem and concluded "route missing"; that error then propagated through STATUS.md, PRP-STATUS.md, the spec, the truth-table, the stability tracker, and the session handoff.

Doc-correction PR: #62. Real B1 code work: see "Real gaps" below — follow-up PR.

What's shipped

• src/lib/payments/payment-service.ts — retryFailedPayment(intentId) retry logic
• Stripe + PayPal webhook handlers (742 LOC Deno)
• src/app/payment-result/page.tsx (commit ffb33a1, 2026-04-16) — 6-state route with auth + Suspense + retry button
• src/components/payment/PaymentStatusDisplay/PaymentStatusDisplay.tsx — status badge + details + real-time updates + retry CTA
• 4 live E2E tests in tests/e2e/payment/03-failed-payment-retry.spec.ts (missing-session, malformed-ID, payment demo loads, consent flow)

Real gaps (this is what B1 actually closes)

In this issue's scope (recommended next PR — gaps 1-5)

1. Retry button regenerates idempotency_key. retryFailedPayment() (src/lib/payments/payment-service.ts:237) calls createPaymentIntent() for a fresh INSERT, which loses the queued idempotency_key and bypasses the partial unique index that landed in PR fix(offline-queue): watchdog reclaim + idempotent payment INSERTs (#52) #59. The retry button on /payment-result should reuse the queued key.
2. No retry attempt counter or cooling period (FR-008, FR-009, FR-010). Currently: unlimited rapid retries permitted.
3. No error categorization (FR-002 — 8 error types defined, none mapped). Current UI shows status === 'failed' with no reason context.
4. No offline error banner.
5. No audit log on retry attempts (NFR-007).

Deferred to a follow-up PR (Stories 3 and 4 — large, P1 in spec but separate scope)

6. User Story 3 — Update Payment Method (FR-011-FR-015). Has stripe.js + PCI surface considerations that warrant their own design pass.
7. User Story 4 — Guided Recovery Wizard (FR-016-FR-019). Largest piece by far.

Reference

• Spec: features/payments/040-payment-retry-ui/spec.md
• PRP: features/payments/040-payment-retry-ui/040_payment-retry-ui_feature.md
• Adjacent existing issues: [Eval-Backlog] PAYMENT-DASHBOARD: user-facing payment dashboard route #3 (/payment-dashboard), [Eval-Backlog] PAYMENT-OFFLINE-UI: UI layer for existing offline payment queue #4 (/payment-history + offline UI), [Eval-Backlog] SUBSCRIPTION-MGMT: subscription management route + 4 edge functions + grace-period wiring #5 (/payment-subscriptions)
• Test-skip index: [Gap-Audit] tests/e2e/payment/: 84 test.skip — index by blocker #53 (closes incrementally as gaps 1-5 land)

[TortoiseWolfe]

Next-session primer

Goal: build /payment/result page, retry surface, and offline error banner — the user-facing piece of the payment retry stack (backend already shipped).

Effort: medium (~half day)
Blocked on: nothing functional, but pairs naturally with payment route work in #3, #4, #5

What's already shipped

• src/lib/payments/payment-service.ts — retry logic
• Stripe + PayPal webhook handlers (742 LOC Deno)
• 2 live + 14 stub tests in tests/e2e/payment/03-failed-payment-retry.spec.ts

Three sub-fixes

A. /payment/result page route

• New src/app/payment/result/page.tsx
• Reads URL query params (?status=success|failed|pending&intent_id=...) — set by Stripe/PayPal redirect after checkout
• Displays appropriate UI: success → confetti + receipt; failed → reason + retry button; pending → polling indicator
• Wraps in <ProtectedRoute> (the auth-race fix from batch 1)
• Use the missing-config banner pattern from PaymentButton when keys aren't set

B. Retry surface UI

• New src/components/molecular/PaymentRetryAffordance/ (5-file)
• Reads from offline queue: usePaymentQueue() or similar
• Shows: failed payments list with retry CTAs
• On click: re-trigger via existing payment-service.ts retry logic

C. Offline error banner

• Reuse useOfflineStatus hook (exists per audit inventory)
• When user is offline and hits a payment route: render banner explaining payment will queue
• Place in src/app/payment/result/page.tsx and any other payment routes

Files

• src/app/payment/result/page.tsx (new) — closes 1 stub
• src/components/molecular/PaymentRetryAffordance/ (new, 5-file) — closes 5+ stubs
• src/components/molecular/OfflinePaymentBanner/ (new, 5-file) — closes ~3 stubs

Coordinates with

• [Eval-Backlog] PAYMENT-DASHBOARD: user-facing payment dashboard route #3 (PAYMENT-DASHBOARD eval-backlog) — /payment/dashboard route
• [Eval-Backlog] PAYMENT-OFFLINE-UI: UI layer for existing offline payment queue #4 (PAYMENT-OFFLINE-UI eval-backlog) — /payment/history route + queue UI
• [Eval-Backlog] SUBSCRIPTION-MGMT: subscription management route + 4 edge functions + grace-period wiring #5 (SUBSCRIPTION-MGMT eval-backlog) — /payment/subscriptions route
• All four payment routes ship together as a coherent set

Verification

1. Mock Stripe checkout success → redirect to /payment/result?status=success → renders confetti page
2. Mock failure → renders retry button → clicking it re-triggers
3. Disable network → visit /payment/result → see offline banner
4. Un-skip the 14 stubs in 03-failed-payment-retry.spec.ts and run

Watch-outs

• Don't ship the routes without confirming Stripe/PayPal sandbox keys are set ([Gap-Audit] 006 Template Fork: add Supabase missing-config first-run banner #24 [Eval-Backlog] SUBSCRIPTION-MGMT: subscription management route + 4 edge functions + grace-period wiring #5) — they'll just show the missing-config banner otherwise