ALwrity/docs/Billing_Subscription/stripe-dev-guide.md

# Stripe Billing & Subscriptions – Developer Guide

This document explains how Stripe is integrated into ALwrity for subscriptions, billing, disputes, and fraud handling. It is aimed at developers working on the backend and frontend.

---

## 1. High-Level Architecture

- **Backend**
  - Core service: `StripeService`  
    - File: `backend/services/subscription/stripe_service.py`
  - Subscription/payment API routes:
    - `backend/api/subscription/routes/payment.py`
    - `backend/api/subscription/routes/disputes.py`
    - `backend/api/subscription/routes/fraud_warnings.py`
  - Models:
    - `UserSubscription`, `SubscriptionPlan`, `BillingCycle`, `UsageStatus`, `FraudWarning`  
      - File: `backend/models/subscription_models.py`
- **Frontend**
  - Pricing and checkout UI:
    - `frontend/src/components/Pricing/PricingPage.tsx`
  - Internal admin dashboards:
    - `frontend/src/pages/StripeDisputesDashboard.tsx`
  - Routing:
    - `frontend/src/App.tsx` (route at `/stripe-disputes`)

Data flows:

- Public users:
  - Browse pricing → select plan → start Stripe Checkout → complete subscription.
- Admin/internal users:
  - Use `/stripe-disputes` dashboard to manage disputes and early fraud warnings.

---

## 2. Configuration & Environment

Required environment variables (backend):

- `STRIPE_SECRET_KEY`
  - Stripe API key (test or live).
- `STRIPE_WEBHOOK_SECRET`
  - Webhook signing secret for subscription webhooks.
- `STRIPE_MODE`
  - Stripe mode selector (`test` or `live`). If unset, mode is inferred from `STRIPE_SECRET_KEY` prefix.
- `STRIPE_PLAN_PRICE_MAPPING_TEST`
  - JSON map for test mode tier/cycle to Stripe price IDs.
- `STRIPE_PLAN_PRICE_MAPPING_LIVE`
  - JSON map for live mode tier/cycle to Stripe price IDs.
- `STRIPE_PLAN_PRICE_MAPPING` (fallback)
  - Optional shared JSON map used only if mode-specific mapping env vars are not set.
- `ADMIN_EMAILS` (optional)
  - Comma-separated list of admin emails allowed to access dispute/fraud endpoints.
- `ADMIN_EMAIL_DOMAIN` (optional)
  - Domain considered admin (e.g. `example.com`).
- `DISABLE_AUTH` (optional)
  - If `"true"`, bypasses admin checks for local/testing use only.

Stripe configuration:

- Price IDs are loaded from environment JSON and validated at backend startup.
- Required mapping keys (fail-fast): `basic.monthly`, `pro.monthly`.
- Mode-specific env vars allow separate test/live values with no code edits.
- Webhook endpoint must be configured in Stripe Dashboard:
  - Path: `/api/subscription/webhook`
  - Events: `checkout.session.completed`, `invoice.payment_succeeded`, `invoice.payment_failed`, `customer.subscription.updated`, `customer.subscription.deleted`, `radar.early_fraud_warning.created` (and optionally `radar.early_fraud_warning.updated`).

---

## 3. Plans, Prices and Mapping

Stripe price mapping is loaded in `StripeService` from env JSON:

- File: `backend/services/subscription/stripe_service.py`

Key structures:

- `STRIPE_PLAN_PRICE_MAPPING`
  - Runtime map of `(SubscriptionTier, BillingCycle)` → Stripe `price_id` parsed from env vars.
- `STRIPE_PRICE_TO_PLAN`
  - Reverse map: `price_id` → `{ tier, billing_cycle }`.

Helper methods:

- `_get_price_id_for_plan(tier, billing_cycle) -> str`
  - Used when creating Checkout sessions.
- `_get_plan_for_price_id(price_id) -> (SubscriptionPlan, BillingCycle)`
  - Used when mapping Stripe subscription items back into our internal `SubscriptionPlan`.

### Adding or updating plans

1. Create prices in Stripe (with correct recurring configuration).
2. Update mapping env vars (`STRIPE_PLAN_PRICE_MAPPING_TEST` / `STRIPE_PLAN_PRICE_MAPPING_LIVE`) with new price IDs.
3. Ensure a `SubscriptionPlan` row exists in the DB for the tier being mapped.
4. Redeploy backend. Startup validation will fail if required keys are missing or mapping JSON is malformed.

---

## 4. Checkout and Subscription Lifecycle

### 4.1 Create Checkout Session

Endpoint:

- `POST /api/subscription/create-checkout-session`
  - File: `backend/api/subscription/routes/payment.py`

Request body:

- `tier: SubscriptionTier` (e.g. `"basic"`, `"pro"`)
- `billing_cycle: BillingCycle` (e.g. `"monthly"`)
- `success_url: str`
- `cancel_url: str`

Flow:

1. Auth middleware resolves `current_user` and `user_id`.
2. `StripeService.create_checkout_session`:
   - Fetches `price_id` via `_get_price_id_for_plan`.
   - Finds or creates Stripe Customer (with `user_id` in metadata).
   - Creates a Stripe Checkout Session:
     - Mode: `subscription`.
     - Metadata: includes `user_id` and `price_id`.
3. Returns `checkout_session.url` to the frontend.

Special handling:

- Metered prices:
  - For metered prices, `quantity` is omitted to comply with Stripe rules.
  - For non-metered prices, `quantity` is set to `1`.

### 4.2 Customer Portal Session

Endpoint:

- `POST /api/subscription/create-portal-session`

Flow:

1. Lookup `UserSubscription` and `stripe_customer_id`.
2. If missing, search Stripe by `metadata['user_id']`.
3. Create Stripe Billing Portal session and return URL.

### 4.3 Webhook Handling

Endpoint:

- `POST /api/subscription/webhook`
  - File: `backend/api/subscription/routes/payment.py`
  - Delegates to `StripeService.handle_webhook`.

Verification:

- `stripe.Webhook.construct_event(payload, sig_header, STRIPE_WEBHOOK_SECRET)` is used to validate signatures.

Handled events:

- `checkout.session.completed`
  - Retrieves subscription and price.
  - Updates `UserSubscription` to active and stores `stripe_customer_id` and `stripe_subscription_id`.
- `invoice.payment_succeeded`
  - Sets `UserSubscription.status` to `ACTIVE`.
  - Updates `current_period_end` from invoice period.
- `invoice.payment_failed`
  - Sets status to `PAST_DUE`, `is_active` false.
- `customer.subscription.updated`
  - Syncs status and `auto_renew`.
- `customer.subscription.deleted`
  - Marks subscription as cancelled and disables auto renew.

Helper:

- `_update_user_subscription` centralizes updating/creating `UserSubscription` records based on Stripe data.

---

## 5. Disputes Integration

Backend routes:

- File: `backend/api/subscription/routes/disputes.py`

Endpoints:

- `GET /api/subscription/disputes`
  - Proxies `stripe.Dispute.list`.
- `GET /api/subscription/disputes/{dispute_id}`
  - Proxies `stripe.Dispute.retrieve`.
- `POST /api/subscription/disputes/{dispute_id}`
  - Proxies `stripe.Dispute.modify` with `evidence`.
- `POST /api/subscription/disputes/{dispute_id}/close`
  - Proxies `stripe.Dispute.close`.

Admin guard:

- `_ensure_admin(current_user)` ensures:
  - Admin by email, domain, or role `"admin"`.
  - Can be bypassed only when `DISABLE_AUTH=true` (local use).

Frontend UI:

- File: `frontend/src/pages/StripeDisputesDashboard.tsx`
- Route: `/stripe-disputes`
- Disputes tab:
  - Lists disputes and allows:
    - Viewing details.
    - Submitting evidence fields:
      - `customer_email_address`, `customer_name`, `customer_purchase_ip`, `access_activity_log`, `uncategorized_text`.
    - Tagging a high-level fraud type, which is encoded into `uncategorized_text`.
    - Closing the dispute.

---

## 6. Early Fraud Warnings (EFW) and Proactive Refunds

### 6.1 Ingestion

Model:

- `FraudWarning` in `backend/models/subscription_models.py`
  - Columns: `id`, `charge_id`, `payment_intent_id`, `user_id`, `amount`, `currency`, `status`, `action`, `action_at`, `reason_notes`, `metadata`, `created_at`.

Ingestion logic:

- `StripeService._handle_early_fraud_warning`:
  - Triggered for event types starting with `radar.early_fraud_warning.`.
  - Retrieves the associated `Charge` to populate amount, currency, and metadata.
  - Infers `user_id` from `charge.metadata.user_id` when available.
  - Upserts a `FraudWarning` row with status `"open"` and action `"none"`.
  - Stores raw EFW and Charge data in `metadata`.

### 6.2 Fraud Warnings API

File: `backend/api/subscription/routes/fraud_warnings.py`

Endpoints:

- `GET /api/subscription/fraud-warnings`
  - Query params:
    - `status` (default `"open"`)
    - `limit`, `offset`
  - Returns a list of warnings with core fields.
- `GET /api/subscription/fraud-warnings/{id}`
  - Returns full details including `metadata`.
- `POST /api/subscription/fraud-warnings/{id}/refund`
  - Performs a **full refund** via `stripe.Refund.create(charge=...)`.
  - Updates `status="refunded"`, `action="refund_full"`, `action_at` and `reason_notes`.
- `POST /api/subscription/fraud-warnings/{id}/ignore`
  - Sets `status="ignored"`, `action="ignored"`, updates notes.

All endpoints apply the same admin guard used for disputes.

### 6.3 Frontend Fraud Warnings Tab

- File: `frontend/src/pages/StripeDisputesDashboard.tsx`

Behavior:

- Adds a tabbed view:
  - Tab 1: Disputes.
  - Tab 2: Fraud Warnings.
- Fraud Warnings tab:
  - Lists EFWs (from `/fraud-warnings`).
  - Shows details including:
    - Stripe EFW `fraud_type`, `actionable` flag.
    - Amount, created time, internal status/action.
  - Allows:
    - Proactive full refund (calls `/fraud-warnings/{id}/refund`).
    - Mark as ignored (calls `/fraud-warnings/{id}/ignore`).
    - Add/update internal notes.

---

## 7. Rate Limiting for Checkout

Endpoint: `POST /api/subscription/create-checkout-session`

File: `backend/api/subscription/routes/payment.py`

Logic:

- Per-user in-memory rate limiting:
  - Window: 60 seconds.
  - Max requests: 10 within the window.
  - On exceed:
    - Logs a warning with `user_id`, IP, attempts count.
    - Returns HTTP 429 with a friendly error message.

Purpose:

- Protects against card testing and abuse by limiting how often a user can create Checkout sessions.

Considerations:

- For multi-instance deployments, a shared store (e.g. Redis) is recommended to make rate limiting consistent across instances.

---

## 8. Extending and Maintaining the Integration

### Adding new subscription tiers or prices

1. Create or update prices in Stripe.
2. Update the relevant mapping environment variable (`STRIPE_PLAN_PRICE_MAPPING_TEST` or `STRIPE_PLAN_PRICE_MAPPING_LIVE`).
3. Ensure corresponding rows in `SubscriptionPlan`.
4. Add any needed frontend logic (e.g. additional tiers in pricing UI).

### Supporting additional Stripe events

- Extend `StripeService.handle_webhook` with new event types.
- Implement corresponding handlers (`_handle_*`) that:
  - Parse event data.
  - Update your DB models.
  - Log with enough context.

### Making the system more robust

- Reintroduce idempotency keys for write operations (Checkout creation, refunds) using stable dedupe keys.
- Replace in-memory rate limiting with shared store-based limiting when scaling horizontally.
- Add more detailed logs/metrics around:
  - New subscriptions.
  - Failed payments.
  - Disputes and early fraud warnings.