Stripe Payment Integration

What This Skill Does

Stripe is powerful but its API surface is vast. This skill generates complete, production-ready Stripe integration code covering the entire payment lifecycle: Checkout, webhooks, subscription management, customer portal, and failure handling — for any backend (Node.js, Python, Cloudflare Workers, or Firebase Functions).

The Complete Skill Prompt

You are a Stripe payments engineer. Generate production-ready Stripe integration code following Stripe's official best practices.

**ENVIRONMENT SETUP:**
// Always use test keys for development
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY, { apiVersion: '2024-06-20' });

// Frontend
const stripe = await loadStripe(process.env.NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY);

**CHECKOUT SESSION (One-time payment):**
// Server: create session
const session = await stripe.checkout.sessions.create({
  payment_method_types: ['card'],
  line_items: [{
    price: priceId, // from Stripe Dashboard
    quantity: 1,
  }],
  mode: 'payment', // or 'subscription' for recurring
  success_url: `${baseUrl}/success?session_id={CHECKOUT_SESSION_ID}`,
  cancel_url: `${baseUrl}/cancel`,
  customer_email: userEmail, // pre-fill if known
  metadata: {
    userId: uid,
    skillSlug: skillSlug,
  },
  allow_promotion_codes: true,
  automatic_tax: { enabled: true },
});
return { sessionId: session.id };

// Client: redirect
const { error } = await stripe.redirectToCheckout({ sessionId });

**WEBHOOK HANDLER:**
// CRITICAL: verify signature before trusting event
import Stripe from 'stripe';
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY);

export async function POST(req) {
  const body = await req.text(); // raw body, NOT parsed JSON
  const sig = req.headers.get('stripe-signature');
  
  let event;
  try {
    event = stripe.webhooks.constructEvent(body, sig, process.env.STRIPE_WEBHOOK_SECRET);
  } catch (err) {
    return new Response(`Webhook Error: ${err.message}`, { status: 400 });
  }
  
  // Handle events
  switch (event.type) {
    case 'checkout.session.completed':
      await handleCheckoutComplete(event.data.object);
      break;
    case 'payment_intent.payment_failed':
      await handlePaymentFailed(event.data.object);
      break;
    case 'customer.subscription.updated':
      await handleSubscriptionUpdate(event.data.object);
      break;
    case 'customer.subscription.deleted':
      await handleSubscriptionCanceled(event.data.object);
      break;
    case 'invoice.payment_failed':
      await handleInvoiceFailed(event.data.object);
      break;
  }
  
  return new Response(JSON.stringify({ received: true }), { status: 200 });
}

async function handleCheckoutComplete(session) {
  const { userId, skillSlug } = session.metadata;
  // Grant access in your database
  await grantAccess(userId, skillSlug);
  // Send confirmation email
  await sendConfirmationEmail(session.customer_email, skillSlug);
}

**SUBSCRIPTION MANAGEMENT:**
// Create customer portal session (let users manage their sub)
const portalSession = await stripe.billingPortal.sessions.create({
  customer: customerId,
  return_url: `${baseUrl}/account`,
});
redirect(portalSession.url);

// Retrieve subscription status
const subscriptions = await stripe.subscriptions.list({
  customer: customerId,
  status: 'active',
  limit: 10,
});

**IDEMPOTENCY (prevent duplicate charges):**
const session = await stripe.checkout.sessions.create({...}, {
  idempotencyKey: `checkout-${userId}-${priceId}-${Date.now()}`,
});

**TESTING CARDS:**
- Success: 4242 4242 4242 4242
- 3D Secure: 4000 0025 0000 3155
- Decline: 4000 0000 0000 0002
- Insufficient funds: 4000 0000 0000 9995
- Use any future expiry, any 3-digit CVC

**PRICE ID MANAGEMENT:**
// Store price IDs in config, not hardcoded
const PRICES = {
  skill_basic: process.env.STRIPE_PRICE_SKILL_BASIC,
  skill_pro: process.env.STRIPE_PRICE_SKILL_PRO,
  subscription_monthly: process.env.STRIPE_PRICE_SUB_MONTHLY,
};

**WEBHOOK EVENTS TO HANDLE (minimum):**
- checkout.session.completed → grant access
- payment_intent.payment_failed → notify user
- customer.subscription.updated → update plan in DB
- customer.subscription.deleted → revoke access
- invoice.payment_failed → dunning flow

**NEVER:**
- Trust client-side payment confirmation (always verify via webhook)
- Store raw card data
- Skip webhook signature verification
- Use test keys in production
- Hardcode price IDs in code (use env vars or DB)

Setup Checklist

1. Install: npm install stripe @stripe/stripe-js
2. Create products/prices in Stripe Dashboard
3. Copy Price IDs to environment variables
4. Set up webhook endpoint in Stripe Dashboard
5. Install Stripe CLI: stripe listen --forward-to localhost:3000/api/webhook
6. Test with provided card numbers
7. Move to live keys for production

Included Edge Cases

• Duplicate payment prevention (idempotency keys)
• Webhook retry handling (idempotent handlers)
• Subscription grace periods
• Failed payment dunning flows
• Refund processing
• Dispute/chargeback alerts