# Stripe Go-Live Checklist This checklist is for preparing ALwrity’s Stripe integration for production. Use it before switching to live keys or onboarding real customers. Tick each item as you complete it. --- ## 1. Configuration & Environment - [ ] **Separate environments set up** - [ ] Test mode Stripe account configured. - [ ] Live mode Stripe account configured. - [ ] **Environment variables configured for production** - [ ] `STRIPE_SECRET_KEY` set to **live** secret key. - [ ] `STRIPE_WEBHOOK_SECRET` set to **live** webhook signing secret. - [ ] `STRIPE_MODE=live` is set (recommended for explicit mode selection). - [ ] `STRIPE_PLAN_PRICE_MAPPING_LIVE` is set to JSON mapping live price IDs. - [ ] (Optional fallback) `STRIPE_PLAN_PRICE_MAPPING` is set only if you intentionally use one shared mapping across environments. - [ ] `ADMIN_EMAILS` configured with correct admin emails (comma-separated). - [ ] `ADMIN_EMAIL_DOMAIN` configured if using domain-based admin access. - [ ] `DISABLE_AUTH` is **not** set to `"true"` in production. - [ ] **Secrets handling** - [ ] No Stripe keys are committed to the repo. - [ ] Secrets are stored only in your deployment platform / secret manager. --- ## 2. Prices, Plans and Mapping - [ ] **All required prices exist in Stripe (live)** - [ ] BASIC monthly price created. - [ ] PRO monthly price created (if used). - [ ] Yearly prices created if you plan to sell yearly plans. - [ ] **Price mapping in backend updated** - [ ] `STRIPE_PLAN_PRICE_MAPPING_LIVE` uses **live** price IDs (not test IDs). - [ ] `STRIPE_PLAN_PRICE_MAPPING_TEST` is configured separately for test deployments. - [ ] Mapping includes required keys: `basic.monthly` and `pro.monthly`. - [ ] Mapping covers any additional tiers and billing cycles you intend to offer. - [ ] **SubscriptionPlan data is consistent** - [ ] DB has `SubscriptionPlan` rows for each tier (BASIC/PRO/etc.). - [ ] `is_active` is set to true for sellable plans. --- ## 3. Database & Migrations - [ ] **Model changes applied in production DB** - [ ] Tables related to subscriptions exist: - [ ] `subscription_plans` - [ ] `user_subscriptions` - [ ] Usage/billing tables exist if used (`api_usage_logs`, `usage_summaries`, etc.). - [ ] `fraud_warnings` table exists for early fraud warnings: - [ ] Checked via DB console or migration logs. - [ ] **Migration strategy verified** - [ ] Any migration scripts run successfully on staging. - [ ] Same process is planned for production. --- ## 4. Webhook Setup - [ ] **Production webhook endpoint configured in Stripe Dashboard** - [ ] URL points to your production backend: - e.g. `https://your-domain.com/api/subscription/webhook` - [ ] Uses HTTPS. - [ ] **Subscribed events include at least** - [ ] `checkout.session.completed` - [ ] `invoice.payment_succeeded` - [ ] `invoice.payment_failed` - [ ] `customer.subscription.updated` - [ ] `customer.subscription.deleted` - [ ] `radar.early_fraud_warning.created` - [ ] (Optional) `radar.early_fraud_warning.updated` - [ ] **Webhook secret set correctly** - [ ] Copy live webhook signing secret from Stripe into `STRIPE_WEBHOOK_SECRET`. - [ ] Confirm no test webhook secret is used in production. - [ ] **Webhook endpoint health check** - [ ] Trigger a test event from Stripe Dashboard (in a safe environment). - [ ] Verify the backend logs show successful verification and handling. --- ## 5. Internal Admin Tools (Ops Readiness) - [ ] **Admin roles/permissions** - [ ] Confirm at least one admin user can access `/stripe-disputes`. - [ ] Non-admin users cannot access sensitive endpoints (disputes, fraud warnings). - [ ] **Disputes dashboard** - [ ] `/stripe-disputes` loads without error. - [ ] Disputes tab can: - [ ] List disputes. - [ ] Show dispute details. - [ ] Submit evidence. - [ ] Close a dispute. - [ ] **Fraud Warnings tab** - [ ] Fraud Warnings tab loads without error. - [ ] List of early fraud warnings is visible when test EFWs exist. - [ ] Details dialog shows: - [ ] Issuer fraud type. - [ ] Actionable flag. - [ ] Internal status / actions. - [ ] Buttons: - [ ] “Refund Full Amount” works (in test/staging). - [ ] “Mark as Ignored” works (updates status). - [ ] **Ops team trained** - [ ] Ops have read the Ops Guide. - [ ] They understand: - [ ] How to respond to disputes. - [ ] When to proactively refund EFWs. - [ ] When to escalate to engineering. --- ## 6. Manual Test Flows (Before Real Customers) Perform these in **test** environment first, then in live with small amounts. ### 6.1 New Subscription Flow - [ ] As a test user: - [ ] Go to Pricing page. - [ ] Select BASIC monthly (or equivalent). - [ ] Start Stripe Checkout and complete payment with test card. - [ ] You are redirected back to the success URL. - [ ] Backend: - [ ] Webhook logs show `checkout.session.completed` processed. - [ ] `UserSubscription` updated with `stripe_customer_id` and `stripe_subscription_id`. - [ ] Subscription status is `ACTIVE`. ### 6.2 Billing Portal - [ ] From the app, open the billing portal (Customer Portal). - [ ] `/api/subscription/create-portal-session` returns a URL. - [ ] You can: - [ ] View invoices. - [ ] Update card details. - [ ] Cancel a subscription. - [ ] After cancellation: - [ ] Webhook logs show `customer.subscription.deleted`. - [ ] `UserSubscription` is updated to cancelled and not active. ### 6.3 Failed Payment (Test Mode) - [ ] Use a known failing test card. - [ ] Trigger a failed invoice. - [ ] Verify: - [ ] `invoice.payment_failed` processed. - [ ] `UserSubscription` status is set to `PAST_DUE` and `is_active` is false. ### 6.4 Dispute (Test Mode) - [ ] Create a test dispute in Stripe’s test mode. - [ ] Confirm: - [ ] Dispute appears in the Disputes tab. - [ ] You can open details and submit evidence. ### 6.5 Early Fraud Warning (Test Mode) - [ ] Create a test Early Fraud Warning (if supported in test mode or via Stripe tools). - [ ] Confirm: - [ ] EFW is ingested and appears in Fraud Warnings tab. - [ ] Details dialog shows issuer `fraud_type` and `actionable` flag. - [ ] “Refund Full Amount” works in test (Stripe shows charge refunded). --- ## 7. Rate Limiting and Abuse Protection - [ ] **Checkout endpoint rate limiting** - [ ] Confirm `create-checkout-session` applies per-user rate limits. - [ ] Hitting the endpoint rapidly produces HTTP 429 and a log entry. - [ ] **Monitoring for card testing** - [ ] Logs for rate-limited events are visible in your logging system. - [ ] You have a plan to investigate suspicious spikes (many 429s or many failed payments). --- ## 8. Monitoring & Alerts - [ ] **Logging** - [ ] Backend logs are centralized (e.g. in a logging service). - [ ] Key Stripe flows (webhooks, disputes, fraud warnings) log useful context. - [ ] **Basic alerting** - [ ] At minimum, you can detect: - [ ] Webhook failures. - [ ] Unusually high dispute volume. - [ ] Frequent early fraud warnings. --- ## 9. Final Production Switch - [ ] **Keys double-checked** - [ ] Production environment uses live Stripe keys and webhook secret. - [ ] No references to test keys remain in production configs. - [ ] **Test charge in live mode** - [ ] Complete a small real transaction in live mode. - [ ] Verify: - [ ] Subscription is active. - [ ] Internal dashboard reflects the subscription correctly. - [ ] Refund/portal flows work as expected. - [ ] **Ops sign-off** - [ ] Ops team confirms they can use Disputes and Fraud Warnings tools comfortably. Once all items are checked, you can consider the Stripe integration ready for production traffic.