Stripe Setup Guide

This guide will walk you through setting up Stripe for subscriptions—from initial account creation to testing and production deployment. Adjust each step to fit your own application’s requirements.

1. Initial Stripe Setup

Create or log into your Stripe account at Stripe Dashboard.
Obtain your test API keys from Developers → API Keys and store them in your environment variables (e.g., .env.local):
Terminal window
```
STRIPE_PUBLIC_KEY=pk_test_...
STRIPE_SECRET_KEY=sk_test_...
```
(Optional) If you plan to use Stripe CLI or advanced features, ensure you have everything installed and configured on your development machine.

2. Products & Prices Configuration

In the Stripe Dashboard, go to Products → Add Product.

Create a “Basic Plan”:

Name: Basic Plan
Description: Basic features subscription
Price: $19/month
API ID: basic-plan

Create a “Pro Plan”:

Name: Pro Plan
Description: Premium features subscription
Price: $29/month
API ID: pro-plan

Copy the Price IDs for each plan. You can store them as environment variables or in a config file:

// Example config snippet
stripe: {
  plans: [
    {
      priceId: process.env.NODE_ENV === "development" ? "price_1234" : "price_5678",
      name: "Basic Plan",
      description: "Perfect for small projects",
      price: 19,
      features: ["NextJS boilerplate", "User OAuth", "Database", "Emails"],
      mode: "subscription",
    },
    {
      priceId: process.env.NODE_ENV === "development" ? "price_ABCD" : "price_EFGH",
      name: "Pro Plan",
      description: "Ideal for advanced projects",
      price: 29,
      features: ["NextJS boilerplate", "User OAuth", "Database", "Emails"],
      mode: "subscription",
    },
  ],
}

Note: Be sure to keep your environment variables secure and avoid committing them to version control.

3. Webhook Configuration

In the Stripe Dashboard, go to Developers → Webhooks.

Add a new endpoint:

https://your-domain.com/api/webhooks/stripe

Select the events you want this endpoint to receive, e.g.:

- customer.subscription.created
- customer.subscription.updated
- customer.subscription.deleted
- checkout.session.completed

Copy the webhook secret and store it in your .env.local file:
Terminal window
```
STRIPE_WEBHOOK_SECRET=whsec_...
```

Tip: You only need to enable the events you actually handle in your code. If you don’t expect customer.subscription.deleted for example, you can skip it. However, it’s often good to handle all subscription lifecycle events for completeness.

4. Local Testing

Install Stripe CLI (for macOS via Homebrew, for example):
Terminal window
```
brew install stripe/stripe-cli/stripe
```
Authenticate the CLI:
Terminal window
```
stripe login
```
Forward webhooks from Stripe to your local development server:
Terminal window
```
stripe listen --forward-to localhost:3000/api/webhooks/stripe
```
Test a checkout session or subscription flow locally. Confirm your endpoint receives the events.

5. Test Integration

Here’s a basic Node.js/TypeScript snippet:

// Create a test customer
const customer = await stripe.customers.create({
  email: 'test@example.com',
});

// Create a subscription for that customer
const subscription = await stripe.subscriptions.create({
  customer: customer.id,
  items: [{ price: 'price_ABC123' }], // Replace with your actual price ID
});

Check your webhook logs (in the CLI or Stripe Dashboard) to confirm events are firing correctly and your application is handling them.

6. Production Setup

Switch to “Live Mode” in the Stripe Dashboard.

Update environment variables with live keys (pk_live_..., sk_live_...):

STRIPE_PUBLIC_KEY=pk_live_...
STRIPE_SECRET_KEY=sk_live_...
STRIPE_WEBHOOK_SECRET=whsec_live_...

Configure production webhooks (e.g., https://my-production-domain.com/api/webhooks/stripe).
Test end-to-end using Stripe’s test cards in live mode with small transactions:
- Successful transaction: 4242 4242 4242 4242
- Fail (Insufficient funds): 4000 0000 0000 9995

Important: Make sure you’re aware of Stripe’s PCI DSS compliance guidelines and are securely handling customer data.

7. Monitoring

To ensure smooth operation:

Enable Fraud Detection (Radar) in your Stripe Dashboard.
Set up Email Notifications for payment failures, disputes, or suspicious activity.
Enable Revenue & Transaction Alerts.
Consider setting up Error Monitoring (e.g., Sentry or other logging services).

8. Final Checklist

Test Keys in development environment
Live Keys in production environment
Webhook endpoints configured and tested
Error Handling implemented for webhook events
Subscription Status updates correctly in your database
Checkout Sessions function as expected
Customer Portal configured (if offering self-service management)
Billing Emails enabled (if you want Stripe to handle receipts/notifications)

Next Steps

Consider Additional Integrations: Billing portal, invoices, and coupon codes.
Review Stripe Docs: For advanced use cases like prorations, usage-based billing, or multi-subscription setups, see the Stripe Documentation.
Stay Compliant: Ensure you follow the latest security practices and regulatory guidelines for handling payment information.

Congratulations! You’ve set up a basic subscription workflow with Stripe. By following these steps and customizing them for your application, you’ll have a solid foundation for testing and rolling out subscription billing. If you need more advanced features or specific payment flows, consult Stripe’s official documentation or reach out to their support.