Implement monetization & paywall (subscriptions + one-time crypto/fiat payments)

[jamespepper81]

Summary

Add monetization to BitSleuth Wallet Analyzer by introducing a flexible paywall and entitlement system that supports:

• Subscriptions (recurring) and one-time purchases (non-recurring)
• Fiat payments via Stripe (recommended for card/subscriptions)
• Crypto payments via BitPay (optional) or another BTC-friendly provider
  Implement backend billing flows, secure webhook handling, frontend gating of premium features, admin dashboard to manage plans, and analytics for revenue and conversion.

Goals

• Provide an extendable billing system to sell premium features / usage tiers
• Support both subscriptions and one-time purchases
• Keep user experience seamless: purchase flow in-app, webhooks to update entitlements
• Secure handling of payment provider secrets and webhooks
• Allow feature gating by entitlement without introducing latency

Non‑goals

• Implementing a custom payment processor (we will integrate Stripe / BitPay)
• Handling accounting / complex invoicing beyond basic receipts and transaction records

Acceptance criteria

• Admins can define plans (monthly/annual tier, price, feature set)
• Users can subscribe or buy one-time features using Stripe (card) or BitPay (crypto)
• Webhooks from payment providers update the system reliably (create/update/cancel)
• Entitlements are enforced on backend APIs and frontend (feature flagging)
• Test suite covers main payment flows and webhook idempotency
• Documentation for env vars, deployment steps, and manual testing is added

High-level design

1) Architecture

Billing service (backend or microservice) for:

• Creating checkout sessions
• Validating and processing webhooks
• Managing subscription records and entitlements
• Emitting events (user, analytics)
• Entitlement table used by auth middleware
• Frontend: purchase modal, account sub page, upgrade flow
• Admin UI: plan management, revenue dashboard

2) Payment providers

Primary: Stripe

• Stripe Checkout for one-time and subscriptions
• Stripe webhooks: invoice.payment_succeeded, customer.subscription.updated, charge.refunded, checkout.session.completed
• Stripe Customer metadata links to platform user_id
  Optional: BitPay (crypto)
• Hosted invoice with webhook/polling
• Model crypto one-time or subscription purchases as above
• Provider-agnostic abstraction (future extensibility)

3) Data model (example)

• plans (id, provider_plan_id, name, price_cents, currency, interval, features JSON)
• subscriptions (id, user_id, plan_id, provider_subscription_id, status, current_period_end, trial_end)
• purchases (id, user_id, plan_id, provider_charge_id, status, amount_cents, created_at)
• entitlements (id, user_id, feature, expires_at/null)
• payment_events (provider, provider_event_id, raw_payload, processed_at, status)

4) Webhooks & security

• Signed webhook verification (Stripe header)
• Store minimal raw payload for audits; mark event processed with idempotency checks
• Retry handling & dead-letter logging for failed webhooks
• Rotate webhook signing secrets & secure in env/secret store

5) API endpoints

• POST /billing/create-checkout-session { plan_id, user_id }
• GET /billing/subscription-status { user_id }
• POST /billing/webhook/{provider }
• Admin: GET/POST /admin/plans, GET /admin/revenue

6) Frontend changes

• Pricing/Plans page, purchase flow UI
• Account → Billing page (plan, next billing date, cancel/upgrade)
• Protected UI components: locked state w/ CTA to upgrade

7) Env / secrets

• STRIPE_SECRET_KEY/WEBHOOK_SECRET
• BITPAY_API_KEY (optional)
• BILLING_WEBHOOK_SECRET (optional)
• BILLING_PROVIDER_MODE = stripe|bitpay|mock

8) Testing

• Unit: webhook processors, entitlement assignment
• Integration: Stripe test mode, or mocked provider
• E2E: checkout flow
• Manual QA: webhooks, cancel, refunds

9) Migration & rollout

• Add DB tables: plans/subscriptions/purchases/entitlements
• Seed free and paid plans in staging
• Feature-flag billing UI
• Enable for subset of users, validate
• Rollout to all

Task breakdown

• Schema design/DB migrations (backend)
• Stripe (checkout & webhook) integration (backend)
• BitPay integration (optional, backend)
• Billing service: endpoints (backend)
• Webhook processing (backend)
• Entitlement enforcement (backend)
• Frontend: plans page, purchase flow
• Frontend: account billing page
• Admin UI basic
• Tests: payments & webhooks
• Docs: env vars, setup, rollout

Security & privacy

• Never store raw card data; Stripe for PCI compliance
• Minimize PII in payment_event logs
• Ensure webhook endpoints are HTTPS, verify signatures
• GDPR/local tax compliance: minimal user payment info

Metrics & analytics

• Track conversion funnel
• Track churn (cancel/renew)
• Revenue numbers in admin dashboard

Estimated effort

• Backend (Stripe, webhooks, entitlement): 2–4 wks
• Frontend (UI, flows): 1–2 wks
• Tests/docs: 1 wk
• BitPay: +1–2 wks (optional)

Suggested labels

• enhancement, monetization, backend, frontend, payments, security

Suggested assignees

• jamespepper81 (existing assignee) + other contributors as needed

Next steps

• Confirm payment providers priority (Stripe req'd, BitPay opt)
• Approve data model fields
• Assign owners backend/frontend
• Make sub-issues from task breakdown