Payments with Stripe

Sabo includes a production-ready Stripe integration with subscription management, checkout sessions, customer portal, and webhook handling. This guide walks you through setup, configuration, and testing.

Overview

Sabo’s Stripe integration provides:

Subscription checkout with Stripe Checkout hosted pages
Plan management via centralized configuration in src/lib/payments/plans.ts
Customer portal for subscription management, payment methods, and invoices
Webhook handling for subscription lifecycle events and payment tracking
Database sync with automatic updates to user_subscriptions and payment_history tables

Quick Start

Get Stripe API keys

Create a Stripe account (or use test mode) and copy your API keys.

Visit Stripe Dashboard → API Keys
Ensure you’re in Test Mode (toggle in top right)
Copy your Publishable key (pk_test_...) and Secret key (sk_test_...)

Never expose your secret key (sk_test_... or sk_live_...) to the browser. Only use it in server-side code and environment variables.

Add Stripe keys to environment

Add the following to your .env.local file:

.env.local

# Site URL (used for Stripe Customer Portal redirects)
NEXT_PUBLIC_SITE_URL=http://localhost:3000

# Stripe API Keys
STRIPE_SECRET_KEY=sk_test_your_secret_key_here
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_test_your_publishable_key_here

# Supabase Secret Key (required for webhooks)
SUPABASE_SECRET_KEY=sb_secret_your_supabase_secret_key

# Webhook secret (filled after Step 4)
STRIPE_WEBHOOK_SECRET=

# Price IDs (filled after Step 3)
NEXT_PUBLIC_STRIPE_PRICE_ID_PRO_MONTHLY=
NEXT_PUBLIC_STRIPE_PRICE_ID_PRO_YEARLY=

NEXT_PUBLIC_SITE_URL must match the origin of your app (e.g., https://yourdomain.com in production). The customer portal route uses this variable to send users back to /dashboard/settings/billing.

Get your Supabase secret key from: Supabase Dashboard → Project Settings → API → Generate new secret key. Secret keys (sb_secret_...) are preferred over service role keys for better security.

Create products and prices

Create the product and prices directly in the Stripe Dashboard:

Go to Stripe Dashboard → Products and click Add product.
Name the product “Pro” (or any plan name that matches your plans.ts configuration).
Under Pricing, add two recurring prices:
- Monthly: $12.00, billing period Monthly
- Yearly: $120.00, billing period Yearly
Save the product and copy the generated price IDs (price_...).

Paste the price IDs into your .env.local file:

.env.local

NEXT_PUBLIC_STRIPE_PRICE_ID_PRO_MONTHLY=price_xxxxx
NEXT_PUBLIC_STRIPE_PRICE_ID_PRO_YEARLY=price_xxxxx

If you change plan names or add additional tiers, mirror those changes in src/lib/payments/plans.ts and create matching prices in Stripe so the price IDs stay in sync.

After updating the values, restart your dev server so the new environment variables are loaded.

Set up webhook forwarding

Webhooks notify your app when subscription events occur (created, updated, cancelled, payments). Choose the approach that fits your environment:

Option A · Stripe CLI (local development)
Option B · Stripe Dashboard (deployed environments)

Install the Stripe CLI (see docs) and log in:

stripe login

Forward events to your local app (keep this terminal running):

stripe listen --forward-to localhost:3000/api/webhooks/stripe

Copy the webhook secret from the CLI output (whsec_...) and add it to .env.local:

.env.local

STRIPE_WEBHOOK_SECRET=whsec_xxxxx

Use two terminals: one for pnpm dev, another for stripe listen. Restart Stripe CLI whenever you restart the dev server.

Go to Stripe Dashboard → Webhooks (use Test mode for staging, Live mode for production).
Add an endpoint: https://yourdomain.com/api/webhooks/stripe.
Subscribe to events: all customer.subscription.* and invoice.payment_* events (or leave set to “send all events” if you prefer).
Copy the signing secret (whsec_...) and add it to your hosting provider’s env configuration (or .env.production):

STRIPE_WEBHOOK_SECRET=whsec_xxxxx

Use separate webhook secrets for test vs. production mode; Stripe generates unique secrets per endpoint.

Test the integration

Start your development server and test the complete flow:

pnpm dev

Visit http://localhost:3000/pricing
Click “Upgrade to Pro”
If not logged in, you’ll be redirected to sign in
After authentication, you’ll be redirected to Stripe Checkout
Use test card 4242 4242 4242 4242 (any future date, any CVC)
Complete checkout and return to the success page 🎉
Visit /dashboard/settings/billing to see your subscription

Verify webhook events are received in the Stripe CLI terminal with “200 OK” responses.

Configuration

Plans Configuration

Sabo centralizes plan configuration in src/lib/payments/plans.ts. This file defines all subscription plans, pricing, features, and Stripe price IDs.

src/lib/payments/plans.ts (excerpt)

export interface Plan {
  id: string;
  name: string;
  description: string;
  monthlyPrice: number | null;
  yearlyPrice: number | null;
  stripePriceIds: { monthly: string | null; yearly: string | null };
  features: string[];
  isPopular: boolean;
  buttonText: string;
  isContactUs?: boolean;
  isFree?: boolean;
}

export const plans: Plan[] = [
  // ...free plan omitted...
  {
    id: "pro",
    name: "Pro",
    description: "Ideal for professionals and small teams",
    monthlyPrice: 12,
    yearlyPrice: 10, // $120/year = $10/month
    stripePriceIds: {
      monthly: process.env.NEXT_PUBLIC_STRIPE_PRICE_ID_PRO_MONTHLY || null,
      yearly: process.env.NEXT_PUBLIC_STRIPE_PRICE_ID_PRO_YEARLY || null,
    },
    features: [
      "Custom domain",
      "SEO-optimizations",
      "Auto-generated API docs",
      "Built-in components library",
      "E-commerce integration",
      "User authentication system",
      "Multi-language support",
      "Real-time collaboration tools",
    ],
    isPopular: true,
    buttonText: "Upgrade to Pro",
  },
  // ...enterprise plan omitted...
];

The pricing component (src/components/marketing/pricing.tsx) automatically reads from this configuration.

To add or modify plans, edit plans.ts, create corresponding products/prices in Stripe, and update the environment variables with new price IDs.

Helper Functions

The same file also exports helper utilities used by pricing UI, API routes, and webhooks:

src/lib/payments/plans.ts (excerpt)

export function getPlanById(planId: string): Plan | undefined {
  return plans.find((plan) => plan.id === planId);
}

export function getPlanByPriceId(priceId: string): Plan | undefined {
  return plans.find(
    (plan) =>
      plan.stripePriceIds.monthly === priceId ||
      plan.stripePriceIds.yearly === priceId
  );
}

export function getBillingCycle(priceId: string): "month" | "year" {
  return plans.some((plan) => plan.stripePriceIds.yearly === priceId)
    ? "year"
    : "month";
}

export function formatPrice(amount: number): string {
  return new Intl.NumberFormat("en-US", {
    style: "currency",
    currency: "USD",
    minimumFractionDigits: 0,
  }).format(amount);
}

These helpers are imported by components such as pricing.tsx and the Stripe webhook handler to keep plan lookups consistent across the app.

API Endpoints

Sabo provides three Stripe API endpoints for subscription management. This section offers a quick overview.

Quick Reference

Endpoint	Purpose	Authentication	Documentation
`POST /api/checkout_sessions`	Create Stripe Checkout session for subscriptions	Required	Full API docs →
`POST /api/customer_portal`	Open Stripe Customer Portal for subscription management	Required	Full API docs →
`POST /api/webhooks/stripe`	Handle Stripe webhook events	Webhook signature	Details below

Common Usage Pattern

Here’s how the pricing page initiates checkout:

src/components/marketing/pricing.tsx (excerpt)

const handleSubscribe = async (priceId: string) => {
  // Create form and submit to checkout endpoint
  const form = document.createElement('form');
  form.method = 'POST';
  form.action = '/api/checkout_sessions';
  
  const input = document.createElement('input');
  input.type = 'hidden';
  input.name = 'price_id';
  input.value = priceId;
  
  form.appendChild(input);
  document.body.appendChild(form);
  form.submit(); // Redirects to Stripe Checkout
};

And accessing the Customer Portal:

src/app/(dashboard)/dashboard/settings/billing/page.tsx (excerpt)

const handleManageSubscription = async () => {
  const response = await fetch('/api/customer_portal', {
    method: 'POST',
    credentials: 'include',
  });
  
  const { url } = await response.json();
  window.location.href = url; // Redirects to Stripe portal
};

For complete endpoint documentation including request/response examples, implementation details, frontend integration, and troubleshooting, see the API Reference.

Need to surface subscription status, cancel buttons, or invoices inside Sabo? Customize the billing settings UI described in Dashboard → Settings; it consumes the same subscription data that Stripe webhooks write.

Webhook Handler

The webhook endpoint (POST /api/webhooks/stripe) is critical for keeping your database in sync with Stripe subscription events.

Supported Events

Event	Trigger	Action
`customer.subscription.created`	New subscription started	Creates `user_subscriptions` record
`customer.subscription.updated`	Subscription changed (plan, status, cancellation)	Updates `user_subscriptions`
`customer.subscription.deleted`	Subscription ended	Marks subscription as deleted
`invoice.payment_succeeded`	Payment successful	Records payment in `payment_history`
`invoice.payment_failed`	Payment failed	Records failed payment

How It Works

src/app/api/webhooks/stripe/route.ts (simplified)

export async function POST(request: Request) {
  // 1. Verify webhook signature
  const signature = request.headers.get("stripe-signature");
  const event = stripe.webhooks.constructEvent(
    body, 
    signature, 
    process.env.STRIPE_WEBHOOK_SECRET
  );
  
  // 2. Process event based on type
  switch (event.type) {
    case "customer.subscription.created":
    case "customer.subscription.updated":
      // Update user_subscriptions table
      const subscription = event.data.object;
      await supabase.from("user_subscriptions").upsert({
        user_id: subscription.metadata.user_id,
        stripe_customer_id: subscription.customer,
        stripe_subscription_id: subscription.id,
        plan_name: getPlanByPriceId(subscription.items.data[0].price.id)?.name,
        status: subscription.status,
        billing_cycle: getBillingCycle(subscription.items.data[0].price.id),
        // ... more fields
      });
      break;
      
    case "invoice.payment_succeeded":
      // Record payment (requires fetching subscription for metadata)
      const invoice = event.data.object;
      const subscriptionId = invoice.subscription;
      const subscription = await stripe.subscriptions.retrieve(subscriptionId);
      const userId = subscription.metadata.user_id;

      await supabase.from("payment_history").insert({
        user_id: userId,
        stripe_subscription_id: subscriptionId,
        amount: invoice.amount_paid,
        currency: invoice.currency,
        status: "succeeded",
        invoice_url: invoice.hosted_invoice_url,
      });
      break;
  }
  
  return new Response(null, { status: 200 });
}

Stripe invoices don’t always include customer metadata directly. The production handler retrieves the subscription (and its metadata) when processing payment events to reliably recover user_id, even for complex invoices (e.g., those generated off-cycle or retried).

Key Implementation Details

Signature Verification

Webhooks verify requests are from Stripe using the STRIPE_WEBHOOK_SECRET:

const event = stripe.webhooks.constructEvent(
  body,
  signature,
  process.env.STRIPE_WEBHOOK_SECRET
);

Without verification, anyone could send fake events to your endpoint. Always verify signatures in production.

User ID from Metadata

When creating checkout sessions, we store user_id in metadata:

// In /api/checkout_sessions
subscription_data: {
  metadata: { user_id: user.id }
}

Webhooks use this metadata to link Stripe subscriptions to your Supabase users.

Plan Name Lookup

Webhooks use getPlanByPriceId() helper to determine plan names:

plan_name: getPlanByPriceId(priceId)?.name

This ensures plan names stay consistent between your UI and database.

RLS Bypass with Service Client

Webhooks need SUPABASE_SECRET_KEY to bypass Row Level Security (RLS):

const supabase = createClient(
  process.env.NEXT_PUBLIC_SUPABASE_URL,
  process.env.SUPABASE_SECRET_KEY // Service client
);

Without this, webhooks can’t write to user_subscriptions or payment_history tables.

Required environment variable: SUPABASE_SECRET_KEYWebhooks use the Supabase service client (not the regular auth client) to bypass Row Level Security when writing subscription data. Without this key, all webhook database operations will fail silently.

Database Schema

Stripe webhooks automatically sync subscription data to two Supabase tables:

user_subscriptions

Stores current subscription state for each user.

Column	Type	Description
`id`	uuid	Primary key
`user_id`	uuid	Foreign key to `auth.users`
`stripe_customer_id`	text	Stripe customer ID (`cus_...`)
`stripe_subscription_id`	text	Stripe subscription ID (`sub_...`)
`stripe_price_id`	text	Current price ID
`plan_name`	text	Human-readable plan name (from `plans.ts`)
`status`	text	`active`, `trialing`, `canceled`, `past_due`, etc.
`billing_cycle`	text	`month` or `year`
`current_period_start`	timestamptz	Start of current billing period
`current_period_end`	timestamptz	End of current billing period
`cancel_at_period_end`	boolean	Will cancel at end of period
`cancel_at`	timestamptz	Scheduled cancellation date
`canceled_at`	timestamptz	When user cancelled
`cancellation_reason`	text	Why cancelled
`trial_start` / `trial_end`	timestamptz	Trial period dates
`created_at` / `updated_at`	timestamptz	Record timestamps

payment_history

Stores all payment transactions for audit and billing history.

Column	Type	Description
`id`	uuid	Primary key
`user_id`	uuid	Foreign key to `auth.users`
`stripe_subscription_id`	text	Related subscription
`stripe_payment_intent_id`	text	Stripe payment intent ID (`pi_...`)
`amount`	integer	Amount in cents (e.g., `1200` = $12.00)
`currency`	text	Currency code (`usd`)
`status`	text	`succeeded` or `failed`
`description`	text	Payment description
`invoice_url`	text	Stripe hosted invoice URL
`created_at`	timestamptz	Payment timestamp

Both tables are automatically created by the Supabase migration in supabase/migrations/20240101000000_create_user_profiles.sql.

For a full tour of every column, Row Level Security policy, and TypeScript type, see the dedicated Database with Supabase guide.

Testing

Test Cards

Stripe provides test cards for various scenarios:

Card Number	Scenario
`4242 4242 4242 4242`	Successful payment
`4000 0000 0000 0002`	Declined payment
`4000 0025 0000 3155`	Requires authentication (3D Secure)
`4000 0000 0000 0341`	Attaches but fails on subsequent charges

Use any future expiration date and any 3-digit CVC.

Testing Checklist

1. Complete Checkout Flow

Test the full user journey from pricing to dashboard:

Visit /pricing while logged out
Click “Upgrade to Pro” → redirected to /sign-in
Sign in and return to pricing
Click “Upgrade to Pro” → redirected to Stripe Checkout
Complete payment with test card
Return to success page
Check /dashboard/settings/billing for subscription details

Expected:

Checkout session opens with correct price
Email is pre-filled
Success page shows after payment
Subscription appears in billing dashboard

2. Webhook Processing

Verify webhooks are received and processed correctly:

Check Stripe CLI terminal for webhook events:

--> customer.subscription.created [200 OK]
--> invoice.payment_succeeded [200 OK]

Check Supabase tables:
- user_subscriptions: New row with subscription data
- payment_history: Payment record with status: "succeeded"
Verify plan name matches plans.ts configuration

Common issues:

400 errors: Wrong STRIPE_WEBHOOK_SECRET
500 errors: Missing SUPABASE_SECRET_KEY
Empty plan_name: Price ID not in plans.ts

3. Customer Portal

Test subscription management via Stripe Customer Portal:

Go to /dashboard/settings/billing
Click “Manage Subscription”
Verify redirect to Stripe Customer Portal
Test updating payment method
Test cancelling subscription
Check webhook events fire (customer.subscription.updated)
Verify cancellation reflected in dashboard

Expected:

Portal loads with correct subscription
Changes sync back to Supabase within seconds
cancel_at_period_end updates to true

4. Yearly vs Monthly Toggle

Test billing cycle switching:

On /pricing, toggle between Monthly and Yearly
Verify prices update (yearly shows discount)
Click “Upgrade to Pro” for yearly
Verify Stripe Checkout shows yearly price ($120/year)
Complete checkout
Check user_subscriptions.billing_cycle is "year"

Expected:

Price toggle animates smoothly
Checkout URL includes yearly price ID
Webhook records correct billing cycle

For end-to-end automation of these scenarios (checkout, portal, cancellation), follow the Playwright testing guide. It includes helpers for logging in with Supabase and examples of asserting billing UI.

Production Deployment

Switch to live mode

In Stripe Dashboard, toggle from Test Mode to Live Mode (top right). Create new products and prices in live mode, or copy test mode products.Update .env (production environment):

STRIPE_SECRET_KEY=sk_live_...  # Live secret key
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_live_...  # Live publishable key
NEXT_PUBLIC_STRIPE_PRICE_ID_PRO_MONTHLY=price_live_...
NEXT_PUBLIC_STRIPE_PRICE_ID_PRO_YEARLY=price_live_...

Create production webhook

In Stripe Dashboard → Webhooks, add a new endpoint:

Endpoint URL: https://yourdomain.com/api/webhooks/stripe
Events to send: Select all:
- customer.subscription.created
- customer.subscription.updated
- customer.subscription.deleted
- invoice.payment_succeeded
- invoice.payment_failed
Copy signing secret and add to production environment as STRIPE_WEBHOOK_SECRET

Production and test mode have separate webhook secrets. Make sure to use the correct secret for each environment.

Test with real payment

Before going live, test with a real small-amount payment:

Create a test plan with a low price ($1 monthly)
Complete checkout with a real card
Verify webhook processing works
Cancel the test subscription
Switch back to your production pricing

Configure Customer Portal

Customize the Stripe Customer Portal for your brand:

Go to Stripe Dashboard → Settings → Customer portal
Configure:
- Branding: Logo, colors, fonts
- Features: Which actions customers can take (cancel, update payment, view invoices)
- Business information: Support email, terms, privacy policy
(Optional) Create a custom portal configuration and set STRIPE_CUSTOMER_PORTAL_CONFIG_ID environment variable

Test the portal at /dashboard/settings/billing after configuration.

Advanced Topics

Handling One-Time Payments

By default, Sabo processes recurring subscriptions. To accept one-time payments (lifetime access, credits, digital products):

Create one-time price in Stripe

In Stripe Dashboard, create a new price with “One time” pricing model instead of “Recurring”.

Add to plans.ts

src/lib/payments/plans.ts

{
  id: "lifetime",
  name: "Lifetime",
  monthlyPrice: 299,  // Display price
  yearlyPrice: null,
  stripePriceIds: {
    monthly: "price_your_onetime_id",  // Reuse monthly field
    yearly: null,
  },
  // ...
}

Modify checkout API

Update src/app/api/checkout_sessions/route.ts to detect one-time vs subscription:

src/app/api/checkout_sessions/route.ts

// Fetch price to check if it's recurring
const price = await stripe.prices.retrieve(price_id);
const mode = price.recurring ? "subscription" : "payment";

const session = await stripe.checkout.sessions.create({
  mode: mode,  // "payment" for one-time, "subscription" for recurring
  line_items: [{ price: price_id, quantity: 1 }],
  // For payment mode, omit subscription_data
  ...(mode === "subscription" && {
    subscription_data: {
      metadata: { user_id: user.id },
    },
  }),
});

Custom Trial Periods

To add trial periods to subscriptions:

src/app/api/checkout_sessions/route.ts

const session = await stripe.checkout.sessions.create({
  // ... other parameters
  subscription_data: {
    trial_period_days: 14,  // 14-day free trial
    metadata: { user_id: user.id },
  },
});

Stripe webhooks automatically track trial start/end dates in user_subscriptions table.

Promotional Codes

Sabo enables promotional codes by default:

src/app/api/checkout_sessions/route.ts

const session = await stripe.checkout.sessions.create({
  allow_promotion_codes: true,  // Customers can enter promo codes
// ...
});

Create promo codes in Stripe Dashboard → Products → Coupons.

Troubleshooting

401 Unauthorized on checkout

Cause: User not authenticated.Fix:

Ensure user is logged in before clicking “Upgrade”
Pricing component automatically redirects to /sign-in if needed
Check sessionStorage.getItem("signin-redirect-to") is working

400 Bad Request - Invalid price ID

Cause: Price ID is null, undefined, or doesn’t exist in Stripe.Fix:

Verify price IDs are set in .env.local
Run npx tsx scripts/setup-stripe-products.ts to create products
Restart dev server after changing env vars
Check price IDs match those in Stripe Dashboard

Webhook signature verification failed

Cause: Wrong STRIPE_WEBHOOK_SECRET or request not from Stripe.Fix:

For local: Copy webhook secret from Stripe CLI output
For production: Copy signing secret from Stripe Dashboard webhook settings
Ensure webhook URL is exactly /api/webhooks/stripe
Check Stripe CLI is running: stripe listen --forward-to localhost:3000/api/webhooks/stripe

Subscription created but not in database

Cause: Missing SUPABASE_SECRET_KEY or webhook processing error.Fix:

Add SUPABASE_SECRET_KEY to environment (get from Supabase Dashboard → Settings → API)
Check webhook handler logs in terminal for errors
Verify user_id is in subscription metadata
Check Supabase table permissions (RLS policies)

Plan name shows as null or 'Unknown Plan'

Cause: Price ID not found in plans.ts.Fix:

Add price ID to stripePriceIds in plans.ts
Ensure environment variables match plan configuration
Webhook uses getPlanByPriceId() to look up plan names

Customer portal not working

Cause: No subscription found or missing customer ID.Fix:

User must have an active subscription first
Check user_subscriptions table has stripe_customer_id
Verify subscription status is not canceled or incomplete
Test creating a new subscription first

Getting Started.

Customization Guides

UI Components

Core Features

Deployment

API Reference

Payments with Stripe

Overview

Quick Start

Configuration

Plans Configuration

Helper Functions

API Endpoints

Quick Reference

Common Usage Pattern

Webhook Handler

Supported Events

How It Works

Key Implementation Details

Database Schema

user_subscriptions

payment_history

Testing

Test Cards

Testing Checklist

Production Deployment

Advanced Topics

Handling One-Time Payments

Custom Trial Periods

Promotional Codes

Troubleshooting

Getting Started.

Customization Guides

UI Components

Core Features

Deployment

API Reference

​Overview

​Quick Start

​Configuration

​Plans Configuration

​Helper Functions

​API Endpoints

​Quick Reference

​Common Usage Pattern

​Webhook Handler

​Supported Events

​How It Works

​Key Implementation Details

​Database Schema

​user_subscriptions

​payment_history

​Testing

​Test Cards

​Testing Checklist

​Production Deployment

​Advanced Topics

​Handling One-Time Payments

​Custom Trial Periods

​Promotional Codes

​Troubleshooting

Overview

Quick Start

Configuration

Plans Configuration

Helper Functions

API Endpoints

Quick Reference

Common Usage Pattern

Webhook Handler

Supported Events

How It Works

Key Implementation Details

Database Schema

user_subscriptions

payment_history

Testing

Test Cards

Testing Checklist

Production Deployment

Advanced Topics

Handling One-Time Payments

Custom Trial Periods

Promotional Codes

Troubleshooting