Skip to main content
Stripe is a good default if you want the most familiar developer payment workflow and full control over products, prices, and metadata.

​
What You Are Setting Up

For Stripe, you need four things:
  1. a product or payment link in Stripe
  2. a checkout URL saved in your env vars
  3. a webhook endpoint in Stripe
  4. a way for the repo to understand what was purchased

​
Required Env Vars

NEXT_PUBLIC_PAYMENT_PROVIDER=stripe
NEXT_PUBLIC_CHECKOUT_URL_TEMPLATE=https://...
STRIPE_SECRET_KEY=...
STRIPE_WEBHOOK_SECRET=...
Optional UI checkout URLs: 
NEXT_PUBLIC_CHECKOUT_URL_PREMIUM=https://...
NEXT_PUBLIC_CHECKOUT_URL_ENTERPRISE=https://...
NEXT_PUBLIC_CHECKOUT_URL_AGENCY=https://...
NEXT_PUBLIC_CHECKOUT_URL_CREDITS_SMALL=https://...
NEXT_PUBLIC_CHECKOUT_URL_CREDITS_LARGE=https://...
Optional product map: 
STRIPE_PRODUCT_MAP='{"prod_123":"anotherwrapper-enterprise"}'

​
Step 1: Create Your Stripe Products

In Stripe:
  1. Open Product catalog
  2. Create a product for each thing you want to sell
  3. Add a price for each product
  4. Create a payment link or checkout flow you want to use in the app
For a simple first setup, create:
  • one Enterprise product
  • one Small credits product

​
Step 2: Decide How Stripe Should Describe The Purchase

You have two good options.

​
Option A: Put type In Metadata

This is the easiest to reason about. Examples:
  • type=anotherwrapper-enterprise
  • type=credits-small
The repo will first look for:
  1. session.metadata.type
  2. product.metadata.type

​
Option B: Use STRIPE_PRODUCT_MAP

If you prefer, keep the mapping in env: 
STRIPE_PRODUCT_MAP='{"prod_123":"anotherwrapper-enterprise","prod_456":"credits-small"}'
This is useful if you do not want to rely on Stripe metadata.

​
Step 3: Add Your Checkout URL To The App

Paste the Stripe payment link into the matching env var in .env.local. Examples: 
NEXT_PUBLIC_CHECKOUT_URL_ENTERPRISE=https://buy.stripe.com/...
NEXT_PUBLIC_CHECKOUT_URL_CREDITS_SMALL=https://buy.stripe.com/...
That is what the app buttons will send users to.

​
Step 4: Add The Webhook In Stripe

In Stripe:
  1. Open Developers -> Webhooks
  2. Add a new endpoint
  3. Use this URL:
https://yourdomain.com/api/payments/stripe
  1. Enable at least:
    • checkout.session.completed
    • checkout.session.async_payment_succeeded
  2. Copy the signing secret into STRIPE_WEBHOOK_SECRET

​
Step 5: Add Your Server Secret Key

Add your Stripe secret key too: 
STRIPE_SECRET_KEY=sk_...
The repo needs this to verify the webhook and inspect the checkout session.

​
How The Repo Processes A Successful Stripe Payment

Once Stripe sends a successful webhook:
  1. the repo verifies the signature
  2. it loads the checkout session
  3. it resolves the purchase type from metadata or STRIPE_PRODUCT_MAP
  4. it stores the purchase in the database
  5. it updates the user’s credits or plan state

​
Verification Checklist

Your Stripe setup is working if:
  • the app opens the Stripe checkout page
  • Stripe shows a successful webhook delivery
  • a row appears in purchases
  • a credits purchase increases the user’s credits
  • a plan purchase updates the user’s purchase state

​
Common Stripe Mistakes

  • using the publishable key instead of STRIPE_SECRET_KEY
  • adding a checkout URL but forgetting the webhook
  • not setting metadata and not setting STRIPE_PRODUCT_MAP
  • using the wrong production domain in the webhook URL