Integrating Stripe Payments: Скилл для Convex + Next.js

--- name: Integrating Stripe Payments description: Complete guide for integrating Stripe payments (subscriptions or one-time) with Convex + Next.js. Includes user interviews, API setup, webhook configuration, testing phases, and production deployment. Use this skill when Adding payment functionality to a Convex + Next.js app --- # Integrating Stripe Payments ## Overview This skill guides you through integrating Stripe payments into a Convex + Next.js application. It covers both subscription and one-time payment flows, with hosted Stripe checkout for simplicity and reliability. **Use this skill when:** - Adding payment functionality to a Convex + Next.js app - Setting up subscription billing - Processing one-time payments - Need to avoid common Stripe + Convex integration mistakes ## Phase 1: Requirements Interview Before starting implementation, gather these requirements from the user: ### Questions to Ask: 1. **Payment Type:** - Subscription (recurring billing) - One-time payment 2. **Backend Confirmation:** - Is this a Convex backend? (Required for this skill) - If not Convex, this skill won't apply 3. **Checkout Preference:** - Hosted Stripe Checkout (recommended - opens in new tab, less complex, more stable) - Embedded Checkout (stays on your site, more complex) 4. **Pricing Details:** - What's the price amount? - What currency? - For subscriptions: billing interval (monthly, every 6 months, yearly)? 5. **Product Information:** - Product name (e.g., "Premium Membership", "Founding Member") - What does the user get after payment? ### Recommended Approach **Strongly recommend:** Hosted Stripe Checkout for subscriptions - Less code complexity - Better mobile support - Stripe handles all payment UI - More stable and secure - Easier to test ## Phase 2: Installation & Dependencies ### 2.1 Install Stripe Package ```bash npm install stripe ``` Note: For hosted checkout, you only need the server-side `stripe` package. No need for `@stripe/stripe-js` or `@stripe/react-stripe-js`. ### 2.2 Database Schema Updates Add Stripe-related fields to your users table in `convex/schema.ts`: ```typescript users: defineTable({ // ... existing fields membershipStatus: v.optional(v.union( v.literal("free"), v.literal("premium"), // or your membership tier name v.literal("past_due") // For failed payments )), membershipExpiry: v.optional(v.number()), // Timestamp when membership expires stripeCustomerId: v.optional(v.string()), // Stripe customer ID stripeSubscriptionId: v.optional(v.string()), // Stripe subscription ID (for subscriptions) }) .index("by_stripe_customer", ["stripeCustomerId"]) .index("by_stripe_subscription", ["stripeSubscriptionId"]) ``` ## Phase 3: API Keys Setup ### 3.1 Get Stripe API Keys 1. Go to [Stripe Dashboard](https://dashboard.stripe.com/) 2. Navigate to **Developers → API keys** 3. Copy your **Test mode** keys: - **Publishable key** (starts with `pk_test_...`) - **Secret key** (starts with `sk_test_...`) ### 3.2 Create Stripe Product & Price 1. In Stripe Dashboard, go to **Products** 2. Click **+ Add Product** 3. Enter product details: - Name: Your product name - Description: What the user gets 4. Add pricing: - **For one-time payments:** Set "One time" pricing - **For subscriptions:** Set "Recurring" and select interval - Enter price amount 5. Click **Save product** 6. Copy the **Price ID** (starts with `price_...`) ### 3.3 Set Environment Variables **In Convex Dashboard** (Settings → Environment Variables): ``` STRIPE_SECRET_KEY=sk_test_your_secret_key_here STRIPE_PRICE_ID=price_your_price_id_here STRIPE_WEBHOOK_SECRET=(we'll get this in Phase 4) ``` **In `.env.local`** (for Next.js frontend): ``` NEXT_PUBLIC_SITE_URL=http://localhost:3000 ``` ## Phase 4: Code Implementation ### 4.1 Create Stripe Actions (`convex/stripe.ts`) ```typescript "use node"; import Stripe from "stripe"; import { action } from "./_generated/server"; import { v } from "convex/values"; import { internal } from "./_generated/api"; /** * Create a Stripe Checkout Session */ export const createCheckoutSession = action({ args: { clerkUserId: v.string(), // Or your auth user ID mode: v.optional(v.union(v.literal("subscription"), v.literal("payment"))), }, handler: async (ctx, args): Promise<{ url: string | null; sessionId: string }> => { const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, { apiVersion: "2025-08-27.basil" as any, }); // Get user from database const user: any = await ctx.runQuery(internal.stripeDb.getUserByClerkId, { clerkId: args.clerkUserId, }); if (!user) { throw new Error("User not found"); } // Create or retrieve Stripe customer let customerId: string | undefined = user.stripeCustomerId; if (!customerId) { const customer = await stripe.customers.create({ email: user.email, name: user.name, metadata: { clerkUserId: args.clerkUserId, convexUserId: user._id, }, }); customerId = customer.id; // Update user with Stripe customer ID await ctx.runMutation(internal.stripeDb.updateStripeCustomerId, { userId: user._id, stripeCustomerId: customerId, }); } const siteUrl = process.env.NEXT_PUBLIC_SITE_URL || "http://localhost:3000"; const mode = args.mode || "subscription"; // Create checkout session const session: Stripe.Checkout.Session = await stripe.checkout.sessions.create({ customer: customerId, mode: mode, // "subscription" or "payment" line_items: [ { price: process.env.STRIPE_PRICE_ID!, quantity: 1, }, ], success_url: `${siteUrl}/checkout/return?session_id={CHECKOUT_SESSION_ID}`, cancel_url: `${siteUrl}`, metadata: { clerkUserId: args.clerkUserId, userId: user._id, }, }); return { url: session.url, sessionId: session.id, }; }, }); /** * Get checkout session status (for return page) */ export const getCheckoutSessionStatus = action({ args: { sessionId: v.string(), }, handler: async (ctx, args) => { const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, { apiVersion: "2025-08-27.basil" as any, }); const session = await stripe.checkout.sessions.retrieve(args.sessionId); return { status: session.status, customerEmail: session.customer_details?.email, paymentStatus: session.payment_status, }; }, }); /** * Create Customer Portal Session * Essential for letting users manage their subscriptions, payment methods, and invoices */ export const createCustomerPortalSession = action({ args: { clerkUserId: v.string(), }, handler: async (ctx, args): Promise<{ url: string }> => { const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, { apiVersion: "2025-08-27.basil" as any, }); // Get user from database const user: any = await ctx.runQuery(internal.stripeDb.getUserByClerkId, { clerkId: args.clerkUserId, }); if (!user || !user.stripeCustomerId) { throw new Error("User not found or has no Stripe customer ID"); } const siteUrl = process.env.NEXT_PUBLIC_SITE_URL || "http://localhost:3000"; // Create portal session const session = await stripe.billingPortal.sessions.create({ customer: user.stripeCustomerId, return_url: `${siteUrl}/dashboard`, }); return { url: session.url, }; }, }); ``` ### 4.2 Create Database Helpers (`convex/stripeDb.ts`) ```typescript import { internalMutation, internalQuery } from "./_generated/server"; import { v } from "convex/values"; /** * Internal query to get user by Clerk ID */ export const getUserByClerkId = internalQuery({ args: { clerkId: v.string(), }, handler: async (ctx, args) => { const user = await ctx.db .query("users") .withIndex("by_clerk_id", (q) => q.eq("clerkId", args.clerkId)) .unique(); return user; }, }); /** * Internal mutation to update user's Stripe customer ID */ export const updateStripeCustomerId = internalMutation({ args: { userId: v.id("users"), stripeCustomerId: v.string(), }, handler: async (ctx, args) => { await ctx.db.patch(args.userId, { stripeCustomerId: args.stripeCustomerId, }); }, }); /** * Internal mutation to update user's membership status after successful payment */ export const updateMembershipStatus = internalMutation({ args: { clerkUserId: v.string(), stripeSubscriptionId: v.string(), // For subscriptions currentPeriodEnd: v.number(), // Timestamp when current period ends }, handler: async (ctx, args) => { const user = await ctx.db .query("users") .withIndex("by_clerk_id", (q) => q.eq("clerkId", args.clerkUserId)) .unique(); if (!user) { throw new Error("User not found"); } await ctx.db.patch(user._id, { membershipStatus: "premium", membershipExpiry: args.currentPeriodEnd * 1000, // Convert to milliseconds stripeSubscriptionId: args.stripeSubscriptionId, }); return user._id; }, }); /** * Internal mutation to cancel user's membership */ export const cancelMembership = internalMutation({ args: { stripeSubscriptionId: v.string(), }, handler: async (ctx, args) => { const user = await ctx.db .query("users") .withIndex("by_stripe_subscription", (q) => q.eq("stripeSubscriptionId", args.stripeSubscriptionId) ) .unique(); if (!user) { console.error("User not found for subscription:", args.stripeSubscriptionId); return null; } await ctx.db.patch(user._id, { membershipStatus: "free", membershipExpiry: undefined, stripeSubscriptionId: undefined, }); return user._id; }, }); /** * Internal mutation to handle payment failure */ export const handlePaymentFailure = internalMutation({ args: { stripeSubscriptionId: v.string(), attemptCount: v.number(), }, handler: async (ctx, args) => { const user = await ctx.db .query("users") .withIndex("by_stripe_subscription", (q) => q.eq("stripeSubscriptionId", args.stripeSubscriptionId) ) .unique(); if (!user) { console.error("User not found for subscription:", args.stripeSubscriptionId); return null; } // You can implement grace period logic here // For example, keep access for 3 failed attempts if (args.attemptCount >= 3) { await ctx.db.patch(user._id, { membershipStatus: "past_due", }); } return user._id; }, }); ``` ### 4.3 Create Webhook Handler (`convex/http.ts`) ⚠️ **CRITICAL: Use `.convex.site` domain for webhooks, NOT `.convex.cloud`** ```typescript import { httpRouter } from "convex/server"; import { httpAction } from "./_generated/server"; const http = httpRouter(); // Stripe webhook handler http.route({ path: "/stripe/webhook", method: "POST", handler: httpAction(async (ctx, request: Request) => { const Stripe = (await import("stripe")).default; const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, { apiVersion: "2025-08-27.basil" as any, }); const body = await request.text(); const sig = request.headers.get("stripe-signature"); if (!sig) { return new Response(JSON.stringify({ error: "No signature" }), { status: 400, }); } try { // ⚠️ CRITICAL: Use constructEventAsync (NOT constructEvent) const event = await stripe.webhooks.constructEventAsync( body, sig, process.env.STRIPE_WEBHOOK_SECRET! ); // Handle the event switch (event.type) { case "checkout.session.completed": { const session = event.data.object as any; const clerkUserId = session.metadata?.clerkUserId; // Handle subscription checkout if (session.mode === "subscription") { const subscriptionId = session.subscription as string; if (!clerkUserId || !subscriptionId) { console.error("Missing clerkUserId or subscriptionId"); break; } // ⚠️ CRITICAL: current_period_end is in subscription.items.data[0] const subscription: any = await stripe.subscriptions.retrieve(subscriptionId); const currentPeriodEnd = subscription.items?.data?.[0]?.current_period_end; if (!currentPeriodEnd) { console.error("No current_period_end found"); break; } // Update user membership const { internal } = await import("./_generated/api.js"); await ctx.runMutation(internal.stripeDb.updateMembershipStatus, { clerkUserId, stripeSubscriptionId: subscriptionId, currentPeriodEnd, }); console.log(`✅ Membership activated for user: ${clerkUserId}`); } // Handle one-time payment checkout if (session.mode === "payment") { // For one-time payments, you might want different logic console.log(`✅ One-time payment completed for user: ${clerkUserId}`); } break; } case "customer.subscription.updated": { // Handle subscription renewal/update const subscription = event.data.object as any; const clerkUserId = subscription.metadata?.clerkUserId; if (!clerkUserId) { console.error("Missing clerkUserId in subscription metadata"); break; } const currentPeriodEnd = subscription.items?.data?.[0]?.current_period_end; if (!currentPeriodEnd) { console.error("No current_period_end found"); break; } // Update membership expiry (handles renewals) const { internal } = await import("./_generated/api.js"); await ctx.runMutation(internal.stripeDb.updateMembershipStatus, { clerkUserId, stripeSubscriptionId: subscription.id, currentPeriodEnd, }); console.log(`✅ Subscription updated for user: ${clerkUserId}`); break; } case "customer.subscription.deleted": { // Handle subscription cancellation const subscription = event.data.object as any; const { internal } = await import("./_generated/api.js"); await ctx.runMutation(internal.stripeDb.cancelMembership, { stripeSubscriptionId: subscription.id, }); console.log(`✅ Subscription canceled: ${subscription.id}`); break; } case "invoice.payment_failed": { // Handle failed payment const invoice = event.data.object as any; const subscriptionId = invoice.subscription; if (!subscriptionId) { console.error("No subscription ID in failed invoice"); break; } const attemptCount = invoice.attempt_count || 0; const { internal } = await import("./_generated/api.js"); await ctx.runMutation(internal.stripeDb.handlePaymentFailure, { stripeSubscriptionId: subscriptionId, attemptCount, }); console.log(`⚠️ Payment failed for subscription: ${subscriptionId}, attempt: ${attemptCount}`); break; } case "invoice.paid": { // Confirm successful payment (handles renewals) const invoice = event.data.object as any; const subscriptionId = invoice.subscription; if (!subscriptionId) { break; // One-time invoice, not subscription } const subscription: any = await stripe.subscriptions.retrieve(subscriptionId); const clerkUserId = subscription.metadata?.clerkUserId; const currentPeriodEnd = subscription.items?.data?.[0]?.current_period_end; if (!clerkUserId || !currentPeriodEnd) { console.error("Missing data for invoice.paid event"); break; } const { internal } = await import("./_generated/api.js"); await ctx.runMutation(internal.stripeDb.updateMembershipStatus, { clerkUserId, stripeSubscriptionId: subscriptionId, currentPeriodEnd, }); console.log(`✅ Invoice paid for user: ${clerkUserId}`); break; } } return new Response(JSON.stringify({ received: true }), { status: 200, }); } catch (err) { console.error("Webhook error:", err); return new Response( JSON.stringify({ error: err instanceof Error ? err.message : "Webhook error" }), { status: 400 } ); } }), }); export default http; ``` ### 4.4 Frontend Integration #### Checkout Button On your frontend, create a button that calls the `createCheckoutSession` action: ```tsx "use client"; import { useAction } from "convex/react"; import { api } from "@/convex/_generated/api"; import { useUser } from "@clerk/nextjs"; import { useState } from "react"; export function UpgradeButton() { const { user } = useUser(); const createCheckoutSession = useAction(api.stripe.createCheckoutSession); const [loading, setLoading] = useState(false); const handleUpgrade = async () => { if (!user) return; setLoading(true); try { const result = await createCheckoutSession({ clerkUserId: user.id, mode: "subscription", // or "payment" for one-time }); if (result.url) { window.open(result.url, "_blank"); } } catch (error) { console.error("Error creating checkout session:", error); } finally { setLoading(false); } }; return ( <button onClick={handleUpgrade} disabled={loading}> {loading ? "Loading..." : "Upgrade to Premium"} </button> ); } ``` #### Customer Portal Button Allow users to manage their subscription, payment methods, and billing: ```tsx "use client"; import { useAction } from "convex/react"; import { api } from "@/convex/_generated/api"; import { useUser } from "@clerk/nextjs"; import { useState } from "react"; export function ManageBillingButton() { const { user } = useUser(); const createPortalSession = useAction(api.stripe.createCustomerPortalSession); const [loading, setLoading] = useState(false); const handleManageBilling = async () => { if (!user) return; setLoading(true); try { const result = await createPortalSession({ clerkUserId: user.id, }); if (result.url) { window.open(result.url, "_blank"); } } catch (error) { console.error("Error creating portal session:", error); } finally { setLoading(false); } }; return ( <button onClick={handleManageBilling} disabled={loading}> {loading ? "Loading..." : "Manage Billing"} </button> ); } ``` ### 4.5 Return Page (`app/checkout/return/page.tsx`) See `resources/return-page-example.tsx` for full implementation with success/error states. ## Phase 5: Webhook Setup & Testing ### 5.1 Get Your Convex HTTP Actions URL ⚠️ **CRITICAL: Use the `.convex.site` domain** 1. Go to Convex Dashboard → **Settings** 2. Find your deployment URL 3. Your webhook URL will be: `https://your-deployment.convex.site/stripe/webhook` - ❌ NOT `.convex.cloud` - ✅ USE `.convex.site` ### 5.2 Create Webhook in Stripe Dashboard 1. Go to **Developers → Webhooks** in Stripe Dashboard 2. Click **+ Add endpoint** 3. Enter webhook URL: `https://your-deployment.convex.site/stripe/webhook` 4. Select events to listen for: - `checkout.session.completed` (required - initial payment) - `customer.subscription.updated` (required - renewals & updates) - `customer.subscription.deleted` (required - cancellations) - `invoice.payment_failed` (required - failed payments) - `invoice.paid` (recommended - successful renewals) 5. Click **Add endpoint** 6. Copy the **Signing secret** (starts with `whsec_...`) 7. Add to Convex environment: `STRIPE_WEBHOOK_SECRET=whsec_...` ### 5.3 Test with Stripe CLI (Optional but Recommended) ```bash # Install Stripe CLI brew install stripe/stripe-cli/stripe # Login stripe login # Forward webhooks to your Convex endpoint stripe listen --forward-to https://your-deployment.convex.site/stripe/webhook ``` ## Phase 6: Dev Mode Testing ### 6.1 Test Checklist - [ ] Start your app: `npm run dev` - [ ] Click upgrade/checkout button - [ ] Verify Stripe checkout page opens in new tab - [ ] Use Stripe test card: - Card: `4242 4242 4242 4242` - Expiry: Any future date - CVC: Any 3 digits - ZIP: Any 5 digits - [ ] Complete payment - [ ] Verify redirect to success page - [ ] Check Convex Dashboard → Data → users table - [ ] Confirm user has updated membership fields - [ ] Check Stripe Dashboard → Webhooks → Events - [ ] Verify webhook was received successfully ### 6.2 Common Issues & Solutions **Issue:** Webhook not receiving events - **Fix:** Confirm you're using `.convex.site` not `.convex.cloud` - **Fix:** Verify webhook secret is set correctly in Convex env vars **Issue:** `SubtleCryptoProvider cannot be used in a synchronous context` - **Fix:** Use `constructEventAsync` not `constructEvent` **Issue:** Membership status not updating - **Fix:** Check `current_period_end` is accessed from `subscription.items.data[0]` - **Fix:** Verify `clerkUserId` is in checkout session metadata ## Phase 7: Customer Portal Configuration The Customer Portal is **essential** for any SaaS product. It allows users to self-manage their subscriptions without contacting support. ### 7.1 Configure Customer Portal in Dashboard 1. Go to [Customer Portal Settings](https://dashboard.stripe.com/settings/billing/portal) in Stripe Dashboard 2. **Business information** - Add your logo, icon, and brand colors - Add support email and phone number - Add Terms of Service and Privacy Policy URLs 3. **Features to enable:** - ✅ **Update payment method** - Let customers add/remove cards - ✅ **Cancel subscriptions** - Choose immediate or end-of-period cancellation - ✅ **Update subscription** - Allow upgrades/downgrades (if you have multiple tiers) - ✅ **Invoice history** - Let customers download past invoices - ✅ **Customer information** - Allow email/address updates 4. Click **Save** ### 7.2 What Customers Can Do in the Portal With the Customer Portal, your customers can: - View current subscription and billing cycle - Update payment methods (add/remove cards) - Cancel or resume subscriptions - View and download all invoices - Update billing information - See payment history **This means less support work for you!** Most billing questions can be self-served. ### 7.3 Portal Best Practices **Where to place the Portal button:** - In account/settings page (always visible) - In subscription status displays - In email receipts (Stripe adds this automatically) **When to show the Portal button:** - Only show to users with `stripeCustomerId` (i.e., users who have subscribed) Example conditional rendering: ```tsx {user.stripeCustomerId && <ManageBillingButton />} ``` ## Phase 8: Payment Failure Handling & Revenue Recovery ~9-15% of subscription payments fail initially, but most are recoverable. Proper handling is **critical** for revenue. ### 8.1 Enable Smart Retries Smart Retries use AI to determine the best time to retry failed payments. **In Stripe Dashboard:** 1. Go to [Revenue Recovery → Retries](https://dashboard.stripe.com/revenue_recovery/retries) 2. Toggle on **Smart Retries** 3. Configure retry settings: - **Number of retries:** 4-8 retries recommended - **Duration:** 2-4 weeks recommended 4. Configure what happens after final retry: - **Recommended:** Mark subscription as unpaid (keeps subscription, stops invoicing) - Alternative: Cancel subscription - Alternative: Leave past_due (keeps invoicing, may annoy customers) 5. Click **Save** ### 8.2 Why Smart Retries Matter - **Success rate:** 15-25% of failed payments succeed on retry - **Revenue recovery:** Can recover thousands per month for mid-size SaaS - **AI-powered:** Retries at optimal times (e.g., after payday for debit cards) - **No work required:** Fully automated once enabled ### 8.3 Handle Failed Payments in Your App Your app should respond to payment failures: ```typescript // Already implemented in convex/stripeDb.ts! export const handlePaymentFailure = internalMutation({ args: { stripeSubscriptionId: v.string(), attemptCount: v.number(), }, handler: async (ctx, args) => { // Grace period logic: keep access for 3 attempts if (args.attemptCount >= 3) { await ctx.db.patch(user._id, { membershipStatus: "past_due", }); } }, }); ``` **User Experience Recommendations:** - Attempts 1-2: Don't revoke access, send gentle reminder email - Attempts 3-4: Revoke access, show "Payment Failed" banner in app - Final retry: Send "Subscription at risk of cancellation" email ### 8.4 Enable Automated Emails (Recommended) 1. Go to [Billing → Revenue recovery → Emails](https://dashboard.stripe.com/revenue_recovery/customer_emails) 2. Enable these emails: - ✅ **Payment failed** - Sent immediately when payment fails - ✅ **Card expiring soon** - Sent 7-15 days before expiry - ✅ **Update payment method** - Sent when card needs updating 3. Customize email templates with your branding 4. Click **Save** **Why this matters:** Automated emails recover 5-10% of failed payments without any manual work. ### 8.5 Monitor Failed Payments **In your Dashboard:** - Go to [Billing → Revenue Recovery](https://dashboard.stripe.com/revenue_recovery) - View recovery rate and revenue recovered - See which customers have failing payments **Set up alerts:** - For high-value subscriptions (>$100/month), notify your sales team of failures - Use webhooks to send Slack notifications for VIP customer failures ## Phase 9: Comprehensive Testing Guide Thorough testing prevents production issues and lost revenue. ### 9.1 Local Webhook Testing with Stripe CLI **Install Stripe CLI:** ```bash # macOS brew install stripe/stripe-cli/stripe # Windows (with Scoop) scoop install stripe # Or download from https://stripe.com/docs/stripe-cli ``` **Forward webhooks to Convex:** ```bash # Login first stripe login # Forward webhooks to your Convex deployment stripe listen --forward-to https://your-deployment.convex.site/stripe/webhook # You'll see a webhook signing secret - add this to Convex env vars temporarily for testing ``` **Test specific events:** ```bash # Test successful subscription creation stripe trigger checkout.session.completed # Test subscription renewal stripe trigger customer.subscription.updated # Test failed payment stripe trigger invoice.payment_failed # Test cancellation stripe trigger customer.subscription.deleted ``` ### 9.2 Test Cards & Scenarios Use these test card numbers in **test mode only:** | Card Number | Scenario | Use Case | |------------|----------|----------| | `4242 4242 4242 4242` | Succeeds | Normal successful payment | | `4000 0025 0000 3155` | Requires authentication | Test 3D Secure flow | | `4000 0000 0000 9995` | Always declines | Test payment failure handling | | `4000 0000 0000 0341` | Attaching requires auth | Test payment method updates | | `4000 0082 6000 0000` | Expires in current year | Test expiring card emails | **Expiry & CVC:** Any future date and any 3-digit CVC work for test cards. ### 9.3 Test Checklist (Before Production) Test all critical flows: **Initial Subscription Flow:** - [ ] User can click "Upgrade" and reach Stripe Checkout - [ ] Test card `4242...` successfully creates subscription - [ ] User redirects to success page after payment - [ ] `membershipStatus` updates to "premium" in Convex - [ ] `membershipExpiry` is set correctly (1 month from now for monthly) - [ ] Webhook `checkout.session.completed` received and processed **Customer Portal Flow:** - [ ] "Manage Billing" button works for subscribed users - [ ] User can view subscription details in portal - [ ] User can update payment method - [ ] User can cancel subscription - [ ] Cancellation triggers `customer.subscription.deleted` webhook - [ ] `membershipStatus` updates to "free" after cancellation **Payment Failure Flow:** - [ ] Use test card `4000 0000 0000 9995` to trigger failure - [ ] `invoice.payment_failed` webhook received - [ ] `handlePaymentFailure` mutation runs correctly - [ ] User sees appropriate message in app after 3 failures - [ ] Smart Retries are scheduled correctly **Renewal Flow:** - [ ] Use Test Clocks to simulate time passage (see below) - [ ] Subscription renews automatically after 1 month - [ ] `customer.subscription.updated` or `invoice.paid` webhook fires - [ ] `membershipExpiry` extends by another month ### 9.4 Test Clocks (Advanced - Simulate Time) Test Clocks let you simulate subscription renewals without waiting weeks/months. **Create Test Clock:** 1. Go to [Workbench → Test Clocks](https://dashboard.stripe.com/test/test-clocks) 2. Click **Create test clock** 3. Set start time to "now" 4. Create customer and subscription using this test clock 5. Advance time by 1 month to test renewal 6. Advance by 3 months to test failed payment retries **With Test Clocks you can test:** - Annual subscription renewals (without waiting 1 year!) - Trial expiration (without waiting 14 days) - Failed payment retry schedules - Proration calculations ### 9.5 Monitor Webhook Delivery **In Stripe Dashboard:** 1. Go to **Developers → Webhooks** 2. Click on your webhook endpoint 3. View **Event deliveries** tab 4. Check for: - ✅ All events have 200 status (success) - ❌ Any 400/500 errors (your webhook failed) - ⏱️ Response times (should be <2 seconds) **Debug failed webhooks:** - Click on failed event to see error message - Use Convex logs to see what went wrong - Use "Resend" button to retry webhook ## Phase 10: Production Deployment ### 10.1 Switch to Live Mode 1. **Get Live API Keys** from Stripe Dashboard (toggle to Live mode) 2. **Create Production Product & Price** in Live mode 3. **Update Convex Production Environment Variables:** ``` STRIPE_SECRET_KEY=sk_live_... STRIPE_PRICE_ID=price_live_... STRIPE_WEBHOOK_SECRET=whsec_live_... ``` 4. **Update Next.js Environment:** ``` NEXT_PUBLIC_SITE_URL=https://yourdomain.com ``` ### 10.2 Create Production Webhook 1. In Stripe Dashboard (Live mode) → Webhooks 2. Add endpoint: `https://your-prod-deployment.convex.site/stripe/webhook` 3. Select all required events (same as test mode) 4. Copy new signing secret 5. Update `STRIPE_WEBHOOK_SECRET` in Convex production env ### 10.3 Configure Customer Portal (Live Mode) 1. Go to [Customer Portal Settings](https://dashboard.stripe.com/settings/billing/portal) (Live mode) 2. Configure same settings as test mode 3. Add your production URLs and branding 4. Enable desired features 5. Click **Save** ### 10.4 Enable Smart Retries (Live Mode) 1. Go to [Revenue Recovery → Retries](https://dashboard.stripe.com/revenue_recovery/retries) (Live mode) 2. Enable Smart Retries with same settings as test mode 3. Enable automated emails for payment failures 4. Click **Save** ### 10.5 Production Test **Test with real payment method (refund immediately after):** - [ ] Complete successful subscription purchase - [ ] Verify webhook delivery in Stripe Dashboard → Webhooks → Event deliveries - [ ] Check user membership updates in production database (Convex Dashboard) - [ ] Test Customer Portal access (update payment method, view invoices) - [ ] Test cancellation flow (cancel and verify webhook + database update) - [ ] Refund the test payment in Stripe Dashboard **Monitor for 24-48 hours:** - [ ] Check webhook success rate (should be 100%) - [ ] Monitor error logs in Convex - [ ] Check first real customer payments process correctly ## Phase 11: Production Best Practices & Webhook Reliability ### 11.1 Webhook Reliability Patterns #### Idempotency - Prevent Duplicate Processing Webhooks may be sent multiple times. Your handler must be idempotent: ```typescript // Add this to convex/stripeDb.ts export const processedWebhookEvents = defineTable({ eventId: v.string(), // Stripe event ID processedAt: v.number(), }).index("by_event_id", ["eventId"]); // Check before processing webhook export const isEventProcessed = internalQuery({ args: { eventId: v.string() }, handler: async (ctx, args) => { const existing = await ctx.db .query("processedWebhookEvents") .withIndex("by_event_id", (q) => q.eq("eventId", args.eventId)) .unique(); return !!existing; }, }); export const markEventProcessed = internalMutation({ args: { eventId: v.string() }, handler: async (ctx, args) => { await ctx.db.insert("processedWebhookEvents", { eventId: args.eventId, processedAt: Date.now(), }); }, }); ``` **Update webhook handler to use idempotency:** ```typescript // In convex/http.ts, before switch statement: const { internal } = await import("./_generated/api.js"); // Check if already processed const isProcessed = await ctx.runQuery(internal.stripeDb.isEventProcessed, { eventId: event.id, }); if (isProcessed) { console.log(`Event ${event.id} already processed, skipping`); return new Response(JSON.stringify({ received: true }), { status: 200 }); } // ... handle event with switch statement ... // After successful processing, mark as processed await ctx.runMutation(internal.stripeDb.markEventProcessed, { eventId: event.id, }); ``` #### Event Ordering - Don't Assume Order Stripe doesn't guarantee event order. Handle events independently: ```typescript // ❌ DON'T rely on event order // Assuming subscription.updated comes before invoice.paid // ✅ DO handle each event independently // Each event should have enough data to process standalone ``` **Best practice:** Always fetch the latest subscription state from Stripe if you need current data: ```typescript case "invoice.payment_failed": { const invoice = event.data.object; // Fetch current subscription state (don't assume from previous events) const subscription = await stripe.subscriptions.retrieve(invoice.subscription); // Now you have accurate current state } ``` ### 11.2 Monitoring & Alerting #### Set Up Monitoring **Webhook health checks:** ```typescript // Create a simple health endpoint in convex/http.ts http.route({ path: "/health", method: "GET", handler: httpAction(async () => { return new Response(JSON.stringify({ status: "ok" }), { status: 200 }); }), }); ``` **Monitor in Stripe Dashboard:** - Go to **Developers → Webhooks** daily (first week of production) - Check "Event deliveries" for any failures - Set up email notifications for webhook failures **Monitor in Convex:** - Check logs for any Stripe-related errors - Monitor subscription creation/update rates - Track failed payment rates #### Set Up Alerts **Critical alerts to implement:** 1. Webhook failure rate > 1% 2. No subscriptions created in 24 hours (if you usually get signups) 3. Failed payment rate > 15% 4. Subscription cancellation spike (>2x normal rate) ### 11.3 Data Consistency **Always sync from Stripe as source of truth:** ```typescript // Good: Periodically sync subscription status from Stripe export const syncSubscriptionStatus = internalMutation({ args: { clerkUserId: v.string(), }, handler: async (ctx, args) => { const user = await ctx.db .query("users") .withIndex("by_clerk_id", (q) => q.eq("clerkId", args.clerkUserId)) .unique(); if (!user || !user.stripeSubscriptionId) return; // Fetch current state from Stripe const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!); const subscription = await stripe.subscriptions.retrieve(user.stripeSubscriptionId); // Update database to match Stripe const currentPeriodEnd = subscription.items?.data?.[0]?.current_period_end; const status = subscription.status === "active" ? "premium" : "free"; await ctx.db.patch(user._id, { membershipStatus: status, membershipExpiry: currentPeriodEnd ? currentPeriodEnd * 1000 : undefined, }); }, }); ``` Run this sync: - When user logs in (to ensure accurate status) - Daily via cron job (for all active subscriptions) - When displaying billing information ### 11.4 Security Best Practices **Protect your API keys:** - Never commit `STRIPE_SECRET_KEY` to git - Use different keys for dev/prod - Rotate keys every 6 months (or immediately if compromised) **Verify webhook signatures:** - Always use `constructEventAsync` (already implemented) - Never trust webhook data without signature verification - Keep `STRIPE_WEBHOOK_SECRET` secure **Limit webhook endpoint access:** - Only accept POST requests (already implemented) - Add rate limiting if you get webhook spam - Monitor for suspicious activity ### 11.5 Common Production Issues & Solutions **Issue: Webhooks stopped working** - Check if Convex deployment URL changed - Verify `STRIPE_WEBHOOK_SECRET` is correct - Check webhook endpoint is enabled in Stripe Dashboard - Look for errors in Stripe → Webhooks → Event deliveries **Issue: Subscriptions not updating after renewal** - Verify `customer.subscription.updated` or `invoice.paid` webhooks are enabled - Check webhook handler processes these events - Verify `current_period_end` is being updated correctly **Issue: Users charged but no access granted** - Check webhook was received (Stripe Dashboard) - Check webhook processed successfully (Convex logs) - Verify database update happened - Check for errors in `updateMembershipStatus` mutation **Issue: Duplicate charges** - Usually caused by retry logic gone wrong - Check you're not calling `stripe.checkout.sessions.create` multiple times - Implement idempotency keys for payment creation ### 11.6 Maintenance Checklist **Weekly:** - [ ] Review webhook delivery success rate - [ ] Check for any unusual failed payments - [ ] Monitor subscription churn rate **Monthly:** - [ ] Review Stripe Dashboard for anomalies - [ ] Check Smart Retries recovery rate - [ ] Audit webhook processing logs - [ ] Review customer support tickets related to billing **Quarterly:** - [ ] Update Stripe SDK version (test in staging first) - [ ] Review and optimize retry settings based on data - [ ] Audit security (rotate API keys) - [ ] Test disaster recovery (webhook failures, database issues) ## Quick Reference Checklist ### Common Mistakes to Avoid 1. ❌ Using `.convex.cloud` for webhooks → ✅ Use `.convex.site` 2. ❌ Using `constructEvent()` → ✅ Use `constructEventAsync()` 3. ❌ Looking for `subscription.current_period_end` → ✅ Use `subscription.items.data[0].current_period_end` 4. ❌ Forgetting to set `STRIPE_WEBHOOK_SECRET` in Convex 5. ❌ Not including `metadata` in checkout session 6. ❌ Only listening to `checkout.session.completed` → ✅ Listen to all lifecycle events 7. ❌ Not configuring Customer Portal → ✅ Essential for production 8. ❌ Not enabling Smart Retries → ✅ Recovers 15-25% of failed payments 9. ❌ Not testing renewal flows → ✅ Use Test Clocks 10. ❌ Not implementing idempotency → ✅ Prevent duplicate processing ### Environment Variables Checklist **Convex Dashboard:** - [ ] `STRIPE_SECRET_KEY` (sk_test_... for dev, sk_live_... for prod) - [ ] `STRIPE_PRICE_ID` (price_... for your product) - [ ] `STRIPE_WEBHOOK_SECRET` (whsec_... from webhook endpoint) **Next.js `.env.local`:** - [ ] `NEXT_PUBLIC_SITE_URL` (http://localhost:3000 for dev, https://yourdomain.com for prod) ### Implementation Checklist **Phase 1-3: Setup** - [ ] Install `stripe` package - [ ] Update database schema with Stripe fields - [ ] Get Stripe API keys (test mode) - [ ] Create product and price in Stripe Dashboard - [ ] Set environment variables **Phase 4: Code Implementation** - [ ] Create `convex/stripe.ts` with checkout and portal actions - [ ] Create `convex/stripeDb.ts` with database helpers - [ ] Create `convex/http.ts` with webhook handler - [ ] Add checkout button to frontend - [ ] Add customer portal button to frontend - [ ] Create return page **Phase 5: Webhooks** - [ ] Get Convex `.convex.site` URL - [ ] Create webhook endpoint in Stripe Dashboard - [ ] Add all required events (checkout, subscription, invoice events) - [ ] Test webhooks with Stripe CLI **Phase 6: Testing** - [ ] Test successful subscription flow - [ ] Test failed payment flow - [ ] Test customer portal (cancel, update payment) - [ ] Test renewal with Test Clocks - [ ] Verify all webhooks process correctly **Phase 7: Customer Portal** - [ ] Configure portal in Stripe Dashboard - [ ] Add branding and business information - [ ] Enable all relevant features - [ ] Test portal as end user **Phase 8: Revenue Recovery** - [ ] Enable Smart Retries - [ ] Configure retry settings (4-8 retries, 2-4 weeks) - [ ] Enable automated emails - [ ] Test payment failure handling - [ ] Monitor recovery dashboard **Phase 9: Comprehensive Testing** - [ ] Complete all test checklist items - [ ] Test with different test cards - [ ] Test subscription lifecycle with Test Clocks - [ ] Verify webhook delivery 100% success rate **Phase 10: Production** - [ ] Switch to live mode API keys - [ ] Create production webhook endpoint - [ ] Configure Customer Portal (live mode) - [ ] Enable Smart Retries (live mode) - [ ] Test with real payment (then refund) - [ ] Monitor for 24-48 hours **Phase 11: Best Practices (Recommended)** - [ ] Implement webhook idempotency - [ ] Add monitoring and alerts - [ ] Set up data consistency sync - [ ] Review security checklist - [ ] Create maintenance schedule ## Phase 12: Advanced Features (Optional) ### 12.1 Free Trials Add a free trial period before charging customers: ```typescript // In convex/stripe.ts - createCheckoutSession const session = await stripe.checkout.sessions.create({ customer: customerId, mode: "subscription", line_items: [{ price: process.env.STRIPE_PRICE_ID!, quantity: 1 }], subscription_data: { trial_period_days: 14, // 14-day free trial }, success_url: `${siteUrl}/checkout/return?session_id={CHECKOUT_SESSION_ID}`, cancel_url: `${siteUrl}`, metadata: { clerkUserId: args.clerkUserId, userId: user._id }, }); ``` **Trial best practices:** - 7-14 days is standard for SaaS - Collect payment method upfront (prevents trial abuse) - Send email 3 days before trial ends - Show trial status in your app UI **Handling trial end:** ```typescript case "customer.subscription.trial_will_end": { // Send reminder email 3 days before trial ends const subscription = event.data.object; // Email user about upcoming charge } ``` ### 12.2 Coupons & Discounts Create and apply discount codes: **Create coupon in Stripe Dashboard:** 1. Go to **Products → Coupons** 2. Click **+ Create coupon** 3. Set discount (% off or fixed amount) 4. Set duration (once, forever, or repeating) 5. Copy coupon ID **Apply coupon to checkout:** ```typescript const session = await stripe.checkout.sessions.create({ customer: customerId, mode: "subscription", line_items: [{ price: process.env.STRIPE_PRICE_ID!, quantity: 1 }], discounts: [{ coupon: "SUMMER2024", // Your coupon code }], // ... rest of session config }); ``` **Allow customers to enter codes:** ```typescript const session = await stripe.checkout.sessions.create({ customer: customerId, mode: "subscription", line_items: [{ price: process.env.STRIPE_PRICE_ID!, quantity: 1 }], allow_promotion_codes: true, // Shows coupon field in checkout // ... rest of session config }); ``` ### 12.3 One-Time Payments For non-subscription purchases (e.g., credits, one-time features): ```typescript // Use mode: "payment" instead of "subscription" const session = await stripe.checkout.sessions.create({ customer: customerId, mode: "payment", // One-time payment line_items: [{ price_data: { currency: "usd", product_data: { name: "100 Credits", description: "One-time credit purchase", }, unit_amount: 999, // $9.99 in cents }, quantity: 1, }], success_url: `${siteUrl}/checkout/return?session_id={CHECKOUT_SESSION_ID}`, cancel_url: `${siteUrl}`, metadata: { clerkUserId: args.clerkUserId, userId: user._id }, }); ``` **Handle one-time payment webhook:** ```typescript case "checkout.session.completed": { const session = event.data.object; if (session.mode === "payment") { // One-time payment completed const clerkUserId = session.metadata?.clerkUserId; // Grant one-time purchase (e.g., add credits) await ctx.runMutation(internal.stripeDb.addCredits, { clerkUserId, amount: 100, }); } } ``` **One-time vs Subscription - When to use which:** - **Subscriptions:** Recurring revenue (monthly/yearly plans) - **One-time:** Credits, lifetime access, course purchases, add-ons ### 12.4 Multiple Subscription Tiers Support different pricing tiers (Basic, Pro, Enterprise): **Setup in Stripe:** 1. Create separate prices for each tier 2. Add price IDs to environment variables: ``` STRIPE_PRICE_ID_BASIC=price_basic... STRIPE_PRICE_ID_PRO=price_pro... STRIPE_PRICE_ID_ENTERPRISE=price_enterprise... ``` **Pass tier in frontend:** ```typescript const result = await createCheckoutSession({ clerkUserId: user.id, mode: "subscription", priceId: "price_pro...", // User selected Pro tier }); ``` **Update createCheckoutSession action:** ```typescript export const createCheckoutSession = action({ args: { clerkUserId: v.string(), mode: v.optional(v.union(v.literal("subscription"), v.literal("payment"))), priceId: v.optional(v.string()), // Allow custom price ID }, handler: async (ctx, args) => { // ... existing code ... const priceId = args.priceId || process.env.STRIPE_PRICE_ID!; const session = await stripe.checkout.sessions.create({ customer: customerId, mode: args.mode || "subscription", line_items: [{ price: priceId, quantity: 1 }], // ... rest of config }); }, }); ``` **Store tier in database:** ```typescript // Update schema membershipTier: v.optional(v.union( v.literal("basic"), v.literal("pro"), v.literal("enterprise") )), // Update in webhook await ctx.db.patch(user._id, { membershipStatus: "premium", membershipTier: "pro", // Store which tier membershipExpiry: currentPeriodEnd * 1000, stripeSubscriptionId: subscriptionId, }); ``` **Customer Portal upgrades/downgrades:** - Configure product catalog in Customer Portal settings - Add all your price tiers - Users can upgrade/downgrade themselves - Stripe handles proration automatically ## Resources - See `resources/common-mistakes.md` for detailed error solutions - See `resources/return-page-example.tsx` for full return page code - [Stripe Checkout Docs](https://docs.stripe.com/checkout) - [Stripe Webhooks Guide](https://docs.stripe.com/webhooks) - [Stripe Customer Portal](https://docs.stripe.com/customer-management) - [Smart Retries](https://docs.stripe.com/billing/revenue-recovery/smart-retries) - [Test Clocks](https://docs.stripe.com/billing/testing/test-clocks) - [Convex HTTP Actions](https://docs.convex.dev/functions/http-actions)