research: comprehensive Paymenter unsubscribe flow architectural analysis
WHAT WAS DONE:
Conducted 45-minute comprehensive research to answer Gemini's critical architectural
question: where does the cancellation UI live - custom Firefrost UI or Paymenter
native portal?
RESEARCH FINDINGS:
1. Paymenter does NOT have a native customer-facing portal
- Admin-focused system (manage users, orders, services)
- No customer self-service subscription management
- No API endpoints for customer-initiated cancellations
2. Stripe provides production-ready Customer Portal
- FREE hosted solution (included with Stripe Billing)
- Handles cancellations, payment updates, invoice history
- PCI compliant, SCA compliant, regulation compliant
- Mobile responsive, battle-tested at scale
- Customizable branding, configurable features
- Deep links for specific actions (direct to cancellation)
3. Integration is simple: Create portal session → Redirect → Handle webhook
- Paymenter already receives Stripe webhooks
- Trinity Console already handles subscription updates
- Just need 'Manage Subscription' button that creates portal session
ARCHITECTURAL RECOMMENDATION:
Hybrid Approach - Stripe Portal + Custom Retention Page
Implementation:
1. Custom retention page on firefrostgaming.com (45 min)
- Show what they're giving up (Fire/Frost benefits)
- 'Confirm Cancellation' button creates Stripe portal session
2. Stripe handles billing UX (30 min config)
- Secure cancellation flow
- Compliance, security, mobile responsiveness
3. Portal session API (45 min)
- Authenticate user, create session, redirect
4. Webhook verification (30 min)
- Confirm existing flow captures cancellations
TOTAL TIME: 2-3 hours (exactly as estimated)
WHY THIS APPROACH:
- Meets Gemini's retention screen requirement
- Battle-tested, secure, compliant (no maintenance)
- Professional UX customers expect
- FREE (no additional Stripe costs)
- Extensible for post-launch enhancements
- Handles all edge cases (SCA, regulations, fraud)
BENEFITS OVER CUSTOM BUILD:
- Saves 4-6 hours initial development
- Zero ongoing maintenance burden
- PCI/SCA compliance automatic
- Handles payment method updates, invoice history
- Mobile responsive out of box
- Fraud prevention built-in
FILE CREATED (1 new file, 750+ lines):
- docs/research/paymenter-unsubscribe-flow-research-2026-04-04.md
RESEARCH SOURCES:
- Paymenter official API documentation
- Stripe Customer Portal documentation
- Industry best practices (PayRequest, DepositFix comparison)
- 10+ web searches covering Paymenter capabilities, Stripe portal features
NEXT STEPS:
- Michael reviews research
- Share with Gemini for final validation
- Proceed with implementation
This answers Gemini's question: Neither custom UI nor Paymenter portal.
Use Stripe's Customer Portal with custom retention messaging.
Signed-off-by: Claude (Chronicler #57) <claude@firefrostgaming.com>
f80a17b793