kunthawat/ALwrity
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
codex/assert-api-endpoints-on-startup
ALwrity/docs/Billing_Subscription/stripe-go-live-checklist.md

7.6 KiB
Raw Permalink Blame History

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.

Reference in New Issue View Git Blame Copy Permalink