Payments

NextSaas provides a complete Stripe integration, including a pricing plugin system, checkout sessions, webhook handling, and a customer portal.

Setup

1. Create Stripe Account: Sign up at Stripe.

2. Get API Keys: Retrieve your Publishable Key and Secret Key from the Stripe Dashboard.

3. Configure Environment:

   NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY="pk_test_..."
   STRIPE_SECRET_KEY="sk_test_..."

Webhooks

Webhooks are crucial for listening to payment events (e.g., checkout.session.completed, invoice.paid).

1. Local Development: Use the Stripe CLI to forward events to your local instance.

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

   Copy the Webhook Signing Secret (whsec_...) from the CLI output to your .env file:

   STRIPE_WEBHOOK_SECRET="whsec_..."

2. Production: In your Stripe Dashboard, go to Developers > Webhooks, add an endpoint: https://your-domain.com/api/stripe/webhook, and select events like checkout.session.completed and customer.subscription.updated.

Pricing Plugins

NextSaas uses a pricing plugin system to manage different pricing models. Each plugin encapsulates its own UI, configuration, and translations.

Activating a Plugin

Set the active plugin via environment variable:

NEXT_PUBLIC_PRICING_PLUGIN="lifetime"

Available Plugins

Product Configuration

For the built-in Lifetime plugin, create a Product and Price in Stripe, then configure:

STRIPE_LIFETIME_PRODUCT_ID="prod_..."
STRIPE_LIFETIME_PRICE_ID="price_..."

Creating a New Plugin

To add a new pricing model (e.g., monthly subscription):

1. Create a new directory under src/lib/pricing/plugins/{name}/ with these files:

   • config.ts — Plan pricing, features, and Stripe IDs
   • i18n.ts — Translations for en and zh-CN
   • component.tsx — Server component for the pricing UI
   • pricing-cta.tsx — Client component for checkout interaction
   • index.ts — Plugin export

2. Register the plugin in src/lib/pricing/registry.ts.

3. Add any new Stripe env vars to src/env.ts.

4. Set NEXT_PUBLIC_PRICING_PLUGIN=your-plugin in .env to activate.

Checkout Flow

We provide a ready-to-use checkout API at src/app/api/stripe/checkout/route.ts.

To initiate a checkout session from the client:

const response = await fetch("/api/stripe/checkout", {
  method: "POST",
  body: JSON.stringify({
    priceId: "price_...",
    successUrl: window.location.origin + "/dashboard",
    cancelUrl: window.location.origin + "/pricing",
  }),
});

const { url } = await response.json();
window.location.href = url;