Stripe + Supabase Payment Demo (Next.js Guide)

Ready to teach yourself (or your team) how to combine Supabase authentication with Stripe Checkout in a modern Next.js application? This guide walks through cloning and running:

• One-time payments and active subscription flows.
• Live and test Stripe mode toggling.
• Supabase-authenticated and secure payment guardrails.

---

1. What You Will Build

Feature	Details
Auth	Supabase email/password login with server-verified sessions
Payments	Stripe Checkout: one-time and subscription
Modes	Toggle between test and live Stripe keys
Security	Prices resolved server-side, session binding, metadata checks
Dashboard	View and cancel subscriptions per environment

---

2. Tech Stack Cheat Sheet

Concern	Implementation
Framework	Next.js 15 (App Router, TypeScript)
Auth	Supabase
Payments	Stripe Checkout Sessions + Subscription APIs
Styling	Tailwind CSS
Deployment	Optimized for Vercel
Source	github.com/owolfdev/stripe-live

---

3. Prerequisites

• Stripe account (test + live mode enabled)
• Supabase project (email/password auth on)
• Node.js 18+ and npm
• Stripe CLI (optional for webhook testing)

---

4. Clone the Repository

bashCopy
git clone https://github.com/owolfdev/stripe-live.git
cd stripe-live
npm install

Main branch contains the production-ready demo used at stripe-live.vercel.app.

---

5. Configure Supabase

In Supabase Dashboard → Auth → Settings:

1. Enable Email/Password sign-in.

2. Add redirect URLs for dev and production:

   • http://localhost:3000
   • https://stripe-live.vercel.app

3. Extract credentials:

SUPABASE_URL
SUPABASE_ANON_KEY
SUPABASE_SERVICE_ROLE_KEY

---

6. Configure Stripe

Create Products and Prices

• Product: Stripe Demo App Product

• Prices:

  • Recurring: basic, standard, premium (monthly)
  • One-time: donate

Mirror these in test and live mode.

Assign lookup keys like:

stripe-live:subscription:basic

Optional Metadata Example

jsonCopy
{
  "app": "stripe-live",
  "store": "default",
  "tier": "basic",
  "billing_type": "subscription",
  "environment": "test"
}

Collect IDs

Copy all price_... values for both test and live into your environment variables.

---

7. Create .env.local

At the project root:

envCopy
# Supabase
NEXT_PUBLIC_SUPABASE_URL=...
NEXT_PUBLIC_SUPABASE_ANON_KEY=...
SUPABASE_SERVICE_ROLE_KEY=...

# Stripe (test)
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=...
STRIPE_SECRET_KEY=...

# Stripe (live)
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY_LIVE=...
STRIPE_SECRET_KEY_LIVE=...

# Stripe price IDs – test mode
STRIPE_TEST_PRICE_DONATE=...
STRIPE_TEST_PRICE_SUB_BASIC=...
STRIPE_TEST_PRICE_SUB_STANDARD=...
STRIPE_TEST_PRICE_SUB_PREMIUM=...

# Stripe price IDs – live mode
STRIPE_LIVE_PRICE_DONATE=...
STRIPE_LIVE_PRICE_SUB_BASIC=...
STRIPE_LIVE_PRICE_SUB_STANDARD=...
STRIPE_LIVE_PRICE_SUB_PREMIUM=...

# Optional
NEXT_PUBLIC_SITE_URL=http://localhost:3000

🔐 Never commit .env.local.

Restart the server after updating env vars.

---

8. Run the App Locally

bashCopy
npm run dev

Visit:

• http://localhost:3000 – Home
• http://localhost:3000/payment – One-time payment
• http://localhost:3000/subscribe – Subscription plans
• http://localhost:3000/subscriptions – Manage active subscriptions
• http://localhost:3000/dashboard – Auth-protected SSR dashboard
• http://localhost:3000/documentation – In-app developer guide

Sign up via email/password to create a Supabase session.

---

9. Payment Flow Overview

1. User selects plan + mode (live/test)
2. Server API verifies Supabase session
3. Server resolves tier slug → Stripe price ID
4. Stripe is queried for current amount + currency
5. Checkout Session created with validated Stripe customer
6. Browser redirects to Stripe Checkout

Subscription listing/cancellation endpoints:

• Confirm Stripe customer ownership
• Validate metadata
• Block cross-app leakage

---

10. Security Highlights

• ✅ Server-owned pricing: clients do not send raw amounts
• ✅ Session validation: Supabase user to Stripe customer mapping
• ✅ Metadata guardrails: safe multi-app Stripe usage
• ✅ Pinned Stripe API version: predictable release behavior

---

11. Deployment

Deploy to Vercel:

bashCopy
vercel

Set all environment variables in Vercel project settings:

• Supabase keys
• Stripe keys
• Price IDs

Different values for:

• Preview (test mode)
• Production (live mode)

Reference implementation:

➡️ https://stripe-live.vercel.app

---

12. Next Steps & Extensions

• Webhooks → Sync Stripe events into Supabase
• Add Stripe Billing Portal for self-service updates
• Tier-based UI gating with Supabase metadata
• Multi-store metadata selectors

---

13. Resources

• Source Code: https://github.com/owolfdev/stripe-live
• Live Demo: https://stripe-live.vercel.app
• Stripe Docs: https://stripe.com/docs
• Supabase Docs: https://supabase.com/docs
• Next.js Docs: https://nextjs.org/docs

---

Happy hacking and safe deployments!