Plainform

Complete guide to setting up Stripe in Plainform, from API keys to webhook configuration and product creation.

Prerequisites

Before setting up Stripe, ensure you have:

A Plainform project installed and running
Node.js 18+ installed
A Stripe account (free tier available)

Stripe is already installed in Plainform (stripe package). You only need to configure environment variables and webhooks.

Quick Setup

Create Stripe Account

Sign up at stripe.com
Complete account verification
Access the Stripe Dashboard

Start in test mode to avoid real charges during development. Toggle to live mode when ready for production.

Get API Keys

In your Stripe Dashboard:

Navigate to Developers → API Keys
You'll see two keys:
- Publishable Key (starts with pk_test_ or pk_live_)
- Secret Key (starts with sk_test_ or sk_live_)
Click "Reveal test key" to copy the secret key

Never commit your Secret Key to version control. It should only be in .env files.

Configure Environment Variables

Add these variables to your .env file in the project root:

Env Variable	Type	Default
`NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY`	`string`	`pk_test_xxxx`
`STRIPE_SECRET_KEY`	`string`	`sk_test_xxxx`
`STRIPE_WEBHOOK_SECRET`	`string`	`whsec_xxxx`

Example .env file:

.env

NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY="pk_test_xxxxxxxxxxxxxxxxxxxx"
STRIPE_SECRET_KEY="sk_test_xxxxxxxxxxxxxxxxxxxx"
STRIPE_WEBHOOK_SECRET="whsec_xxxxxxxxxxxxxxxxxxxx"

These variables are validated on startup by env.ts. The app won't start if any required variable is missing or invalid.

Set Up Webhook Endpoint

Webhooks notify your app of payment events. Set up the endpoint:

In Stripe Dashboard, go to Developers → Webhooks
Click Add endpoint
Enter your webhook URL:
- Development: Use Stripe CLI (see below)
- Production: https://yourdomain.com/api/stripe/webhook
Select events to listen for:
- checkout.session.completed
- payment_intent.succeeded
- payment_intent.payment_failed
- customer.subscription.created
- customer.subscription.updated
- customer.subscription.deleted
Click Add endpoint
Copy the Signing secret (starts with whsec_)
Add it to your .env as STRIPE_WEBHOOK_SECRET

For local development:

Terminal

# Install Stripe CLI
# Windows: scoop install stripe
# Mac: brew install stripe/stripe-cli/stripe
# Linux: See https://stripe.com/docs/stripe-cli

# Login to Stripe
stripe login

# Forward webhooks to local server
stripe listen --forward-to localhost:3000/api/stripe/webhook

The CLI will output a webhook signing secret - use this for STRIPE_WEBHOOK_SECRET in development.

Verify Setup

Start your development server:

Start dev server

npm run dev

If configuration is correct, you'll see:

No validation errors in the terminal
The app starts successfully on http://localhost:3000

If you see errors, double-check:

Variable names match exactly (case-sensitive)
Keys are copied correctly from Stripe Dashboard
.env file is in the project root

Create Products

Create products in Stripe Dashboard to display in your pricing section:

Go to Products in Stripe Dashboard
Click Add product
Fill in product details:
- Name: Product name (e.g., "Pro Plan")
- Description: Product description
- Image: Upload product image (optional)
- Pricing: Set price and billing interval
Click Save product

For one-time payments:

Set pricing model to "One time"
Enter price amount

For subscriptions:

Set pricing model to "Recurring"
Choose billing interval (monthly, yearly, etc.)

Test Checkout Flow

Test the payment flow with Stripe test cards:

Navigate to your pricing page
Click a "Buy Now" button
Use test card: 4242 4242 4242 4242
Use any future expiry date and any CVC
Complete checkout
Check Stripe Dashboard → Payments to see the test payment

In test mode, no real money is charged. Use Stripe test cards to simulate different scenarios.

Stripe Client Configuration

The Stripe client is initialized in lib/stripe/stripe.ts:

lib/stripe/stripe.ts

import { env } from '@/env';
import 'server-only';
import Stripe from 'stripe';

export const stripe = new Stripe(env.STRIPE_SECRET_KEY);

Key points:

Uses 'server-only' directive to prevent client-side usage
Automatically uses API version from Stripe SDK
Environment variable validated by env.ts

Manual Capture Configuration

Plainform uses manual capture for one-time payments. This is configured in the checkout route:

app/api/stripe/checkout/route.ts

const session = await stripe.checkout.sessions.create({
  // ... other config
  payment_intent_data: {
    capture_method: 'manual',
  },
});

Why manual capture?

Review orders before charging customers
Verify order details (e.g., customer email)
Cancel fraudulent or invalid orders
Capture payment after order verification

To capture or cancel:

Use Stripe Dashboard → Payments → Capture/Cancel
Or use Stripe API (see Usage & Integration docs)

Development vs Production

Development Setup

Use test keys (pk_test_, sk_test_)
Test mode in Stripe Dashboard
Use Stripe CLI for local webhooks
Test cards for payments (no real charges)

Testing webhooks locally:

Terminal

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

Production Setup

Use live keys (pk_live_, sk_live_)
Production mode in Stripe Dashboard
Configure webhook endpoint with your domain
Real payments processed

Environment Variables:

Set these in your hosting platform (Vercel, etc.):

NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY (live key)
STRIPE_SECRET_KEY (live key)
STRIPE_WEBHOOK_SECRET (from production webhook endpoint)

Verification

After setup, verify everything works:

Products Display: Check pricing section shows products
Checkout Flow: Click "Buy Now" and complete test checkout
Webhook Events: Verify webhooks received in Stripe Dashboard
Database Sync: Check orders saved to database (if applicable)
Manual Capture: Test capturing payment in Stripe Dashboard

Next Steps

Usage & Integration

Learn how to create checkouts and handle webhooks

Troubleshooting

Fix common payment integration issues

Stripe Documentation

Official Stripe documentation

Setup & Configuration