Stripe Integration 💳

Let's set up Stripe payments for your Indie Kit application! 🚀

Initial Setup ⚡

1. Create a Stripe account

2. Set up your business details

3. Add required legal documents:

   • Privacy Policy
   • Terms of Service

4. Add these environment variables to your .env file:

   # Stripe Configuration
   STRIPE_WEBHOOK_SECRET=whsec_xxx...    # From Stripe webhook settings
   STRIPE_PUBLISHABLE_KEY=pk_test_xxx... # From Stripe API keys
   STRIPE_SECRET_KEY=sk_test_xxx...      # From Stripe API keys

   🔒 Security Note: Never commit these keys to your repository. In production, add them securely to your hosting platform's environment variables.

   💡 Testing vs Production: Keys starting with pk_test_ and sk_test_ are for testing. Use pk_live_ and sk_live_ in production.

Product Configuration 🛍️

In your Stripe Dashboard:

1. Create Products with pricing:
   • Monthly subscriptions
   • Yearly subscriptions
   • One-time payments
2. Enable Customer Portal:
   • Go to Settings → Customer Portal
   • Add products for upgrade/downgrade flows
   • Configure branding

Webhook Setup 🔌

1. Add your webhook endpoint in Stripe Dashboard:

   https://your-domain.com/api/webhooks/stripe

2. Enable these webhook events:

   • invoice.paid
   • customer.created
   • customer.subscription.created
   • customer.subscription.updated
   • customer.subscription.deleted

   💡 Important: All these events are required for proper subscription management. They handle:

   • Customer creation and management
   • Subscription lifecycle (creation, updates, deletion)
   • Invoice payments

3. For local testing, use Stripe CLI:

   # Login to Stripe
   stripe login
   
   # Forward webhooks to your local server
   stripe listen --forward-to http://localhost:3000/api/webhooks/stripe

Plan Mapping 🗺️

1. Go to your super admin dashboard: /super-admin/plans
2. For each plan, add the corresponding Stripe Price IDs:
   • monthlyStripePriceId
   • yearlyStripePriceId
   • onetimeStripePriceId

💡 Tip: Find Price IDs in Stripe Dashboard under Products → Select Product → Pricing

Adding Subscribe Buttons 🔘

Use the getSubscribeUrl helper to create subscription links:

import getSubscribeUrl, { PlanType, PlanProvider } from '@/lib/plans/getSubscribeUrl'

function PricingCard({ plan }) {
  // Monthly subscription with 7-day trial
  const monthlyUrl = getSubscribeUrl({
    codename: plan.codename,
    type: PlanType.MONTHLY,
    provider: PlanProvider.STRIPE,
    trialPeriodDays: 7
  })

  // Yearly subscription with 14-day trial
  const yearlyUrl = getSubscribeUrl({
    codename: plan.codename,
    type: PlanType.YEARLY,
    provider: PlanProvider.STRIPE,
    trialPeriodDays: 14
  })

  // One-time payment
  const onetimeUrl = getSubscribeUrl({
    codename: plan.codename,
    type: PlanType.ONETIME,
    provider: PlanProvider.STRIPE
  })

  return (
    <div className="pricing-card">
      <h2>{plan.name}</h2>
      <div className="buttons">
        {plan.hasMonthlyPricing && (
          <Link href={monthlyUrl}>
            <Button>Subscribe Monthly</Button>
          </Link>
        )}
        {plan.hasYearlyPricing && (
          <Link href={yearlyUrl}>
            <Button>Subscribe Yearly</Button>
          </Link>
        )}
        {plan.hasOnetimePricing && (
          <Link href={onetimeUrl}>
            <Button>Buy Lifetime</Button>
          </Link>
        )}
      </div>
    </div>
  )
}

Features Available 🎯

• 🔄 Automatic plan upgrades/downgrades
• 💳 Stripe-managed billing
• 🏪 Customer portal for subscription management
• ⚡ Webhook handling
• 🔍 Payment tracking
• 📊 Usage monitoring

Best Practices 💡

1. Testing

   • Use Stripe CLI for local webhook testing
   • Test all subscription flows
   • Verify upgrade/downgrade paths

2. Production

   • Add all required legal documents
   • Configure proper webhook security
   • Monitor webhook events
   • Set up alerts for failed payments

3. Customer Experience

   • Clear pricing information
   • Smooth upgrade flow
   • Easy access to billing portal
   • Clear trial period information

Now your Indie Kit application is ready to accept payments and manage subscriptions through Stripe! 🎉