Add Stripe Payments

Use this skill when the user asks to add payments, billing, subscriptions, or Stripe integration.

Steps

1. Install the SDK

   npm install stripe @stripe/stripe-js
   

2. Add environment variables

   STRIPE_SECRET_KEY=sk_test_...
   NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_...
   STRIPE_WEBHOOK_SECRET=whsec_...
   

3. Create a Stripe client module — create lib/stripe.ts:

   import Stripe from "stripe";
   
   export const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!, {
     apiVersion: "2024-12-18.acacia",
   });
   

4. Create a checkout API route — create an endpoint that creates a Stripe Checkout session:

   const session = await stripe.checkout.sessions.create({
     mode: "subscription", // or "payment" for one-time
     payment_method_types: ["card"],
     line_items: [{ price: priceId, quantity: 1 }],
     success_url: `${origin}/success?session_id={CHECKOUT_SESSION_ID}`,
     cancel_url: `${origin}/pricing`,
     customer_email: userEmail,
   });
   return redirect(session.url!);
   

5. Create a webhook handler — create a POST endpoint at /api/webhooks/stripe:

   • Verify the webhook signature using stripe.webhooks.constructEvent.
   • Handle key events: checkout.session.completed, customer.subscription.updated, customer.subscription.deleted, invoice.payment_failed.
   • Update your database with the subscription status.

6. Add customer portal (optional) — create an endpoint that redirects to stripe.billingPortal.sessions.create so users can manage their subscription.

7. Add pricing page UI — create a pricing page with plan cards that call the checkout API route.

Notes

• Always verify webhook signatures — never trust unverified payloads.
• Use Stripe CLI (stripe listen --forward-to localhost:3000/api/webhooks/stripe) for local webhook testing.
• Store the Stripe customer ID in your user database to avoid creating duplicate customers.
• Use stripe.prices.list to fetch prices dynamically instead of hardcoding them.