just.another.template

Back to Documentation

Payments

This template includes a complete Stripe integration for handling payments, subscriptions, and billing management.

Overview

The payments system is built on Stripe's API and provides a comprehensive solution for handling various aspects of payments and subscriptions. It includes server-side integration with Stripe's API and client-side components for payment collection and management.

The integration is designed to be developer-friendly while providing all the features needed for a production-ready payment system.

Features

Webhooks

Built-in handlers for Stripe webhooks to process events such as payments, subscription updates, and invoice processing.

User Management

Tools for managing user subscriptions including pausing, canceling, and upgrading subscription plans.

Portal Banner Alert

Customizable banner alerts with CTAs for customers with errored payments or subscription issues.

Dunning Management

Automatic payment retry system to recover failed payments and reduce churn.

Subscription Management

Complete subscription lifecycle management from creation to cancellation.

Implementation

The Stripe integration is implemented in the src/server/stripe directory and includes:

  • API Client: A typed Stripe API client for server-side operations.
  • Webhook Handlers: Predefined handlers for all relevant Stripe webhook events.
  • Subscription Logic: Business logic for handling subscriptions and upgrades.
  • User Management: Integration with the user system for managing customer data.
  • UI Components: React components for payment forms, subscription management, and billing information.

Stripe Webhook Setup

To use Stripe webhooks in your development environment, you'll need to set up the Stripe CLI to forward events to your local server:

# Install the Stripe CLI
brew install stripe/stripe-cli/stripe

# Login to your Stripe account
stripe login

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

For production, you'll need to configure the webhook URL in your Stripe dashboard and set the webhook secret in your environment variables.

Usage Example

Here's an example of how to create a checkout session:

// Server-side API route to create a checkout session
import { stripe } from "@/server/stripe/client";
import { NextResponse } from "next/server";

export async function POST(req: Request) {
  try {
    const { priceId, customerId } = await req.json();
    
    const session = await stripe.checkout.sessions.create({
      customer: customerId,
      line_items: [{ price: priceId, quantity: 1 }],
      mode: "subscription",
      success_url: `${process.env.NEXT_PUBLIC_APP_URL}/payment/success?session_id={CHECKOUT_SESSION_ID}`,
      cancel_url: `${process.env.NEXT_PUBLIC_APP_URL}/payment/canceled`,
    });
    
    return NextResponse.json({ url: session.url });
  } catch (error) {
    return NextResponse.json({ error: "Failed to create checkout session" }, { status: 500 });
  }
}

Configuration

Stripe settings can be configured in the .env file. The following environment variables are required:

  • STRIPE_SECRET_KEY: Your Stripe secret key
  • STRIPE_WEBHOOK_SECRET: The signing secret for your Stripe webhook
  • NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY: Your Stripe publishable key