Payments

Stripe integration is pre-configured. Here's how to activate and customize your payment system.

Quick Setup

1. Create Stripe products in your dashboard
2. Configure webhook endpoint
3. Test the payment flow

Stripe Products Configuration

Create Your Plans

In Stripe Dashboard → Products, create:

Basic Plan
- Monthly: $9/month
- Annual: $90/year (save $18)

Pro Plan
- Monthly: $29/month
- Annual: $290/year (save $58)

Copy the price IDs to use in your pricing page.

Pricing Page Setup

Update app/pricing/page.tsx with your price IDs:

const plans = [
  {
    name: 'Basic',
    monthlyPriceId: 'price_1234567890',
    annualPriceId: 'price_0987654321',
    price: { monthly: 9, annual: 90 },
  },
  {
    name: 'Pro',
    monthlyPriceId: 'price_abcdefghij',
    annualPriceId: 'price_jihgfedcba',
    price: { monthly: 29, annual: 290 },
  },
];

Payment Flow

Subscription Creation

1. User clicks "Subscribe" on pricing page
2. Redirects to Stripe Checkout with price ID
3. User completes payment
4. Webhook updates subscription in database
5. User redirected to success page

Webhook Handling

The webhook endpoint (/api/webhooks/stripe) handles:

• customer.subscription.created - New subscription
• customer.subscription.updated - Plan changes
• customer.subscription.deleted - Cancellations
• invoice.payment_succeeded - Successful payments
• invoice.payment_failed - Failed payments

Billing Portal

Users manage subscriptions via Stripe's hosted portal:

// Redirect to billing portal
const { url } = await stripe.billingPortal.sessions.create({
  customer: user.stripe_customer_id,
  return_url: `${process.env.NEXT_PUBLIC_SITE_URL}/billing`,
});

Accessible at /billing/portal - handles upgrades, downgrades, cancellations.

Subscription Status

User subscription status is stored in the profiles table:

// Check if user has active subscription
const hasActiveSubscription = user.subscription_status === 'active'

// Protect premium features
if (!hasActiveSubscription) {
  return <UpgradeBanner />
}

Testing Payments

Test Mode Setup

1. Use test API keys from Stripe
2. Test card numbers: 4242 4242 4242 4242
3. Any future date for expiry
4. Any 3-digit CVC

Test Scenarios

• Successful payment
• Declined card
• Webhook delivery
• Subscription changes

Production Setup

Webhook Configuration

1. Add webhook endpoint: https://yourdomain.com/api/webhooks/stripe
2. Select events: customer.subscription.*, invoice.*
3. Copy webhook secret to STRIPE_WEBHOOK_SECRET

Go Live

1. Switch to live API keys
2. Test with real payment methods
3. Verify webhook delivery
4. Monitor Stripe dashboard

Customization

Custom Checkout

Replace Stripe Checkout with embedded form using Stripe Elements for more control.

Usage-Based Billing

Add metered billing for API calls or usage limits using Stripe's usage records.

Multiple Payment Methods

Enable additional payment methods (ACH, SEPA, etc.) in Stripe settings.

Troubleshooting

Webhook not firing: Check endpoint URL and selected events Payment failed: Verify API keys and test card numbers
Subscription not updating: Check webhook signature validation Portal not loading: Verify customer ID exists