🚀StarShip Developer Kit

Stripe Integration

Overview

The Next.js 15 StarShip Developer Kit includes a comprehensive Stripe integration that supports both one-time payments and subscription models, with minimal configuration required.

Why This Implementation Excels

  • Seamless Authentication Integration: Stripe customers are automatically linked to NextAuth users with no additional configuration required
  • Complete User Journey: Ready-to-use checkout flows, success/cancel pages, and user purchase history
  • Subscription Management: Built-in subscription lifecycle handling including cancellations and renewals
  • Comprehensive Webhooks: Pre-configured webhook handling for all critical payment events
  • Mobile Payment Support: Apple Pay and Google Pay integration ready to activate
  • Email Notifications: Automatic email notifications for payment events through the integrated SMTP system

User Management & Purchase History

The kit includes a complete user-facing subscription and purchase management system:

Profile Page Features

A dedicated profile page at /profile allows users to:

  • View their complete purchase history
  • See active subscriptions and their activation dates
  • Cancel active subscriptions
  • Reactivate previously canceled subscriptions
  • Update payment methods (through Stripe Customer Portal)

This fully integrated system connects user authentication with payment processing, creating a seamless experience for both users and administrators.

Zero-configuration user linking: Stripe customers are automatically created and linked to NextAuth users behind the scenes - you don't need to write any additional code to make this connection work.

Prerequisites

  • A Stripe account (you can use the test mode for development)
  • Stripe API keys (publishable key and secret key)
  • Stripe CLI for webhook testing (optional but recommended)

Environment Configuration

Configure the following environment variables in your .env file:

  • STRIPE_PUBLISHABLE_KEY - Your Stripe publishable key
  • STRIPE_SECRET_KEY - Your Stripe secret key
  • STRIPE_WEBHOOK_SECRET - Your Stripe webhook secret
  • STRIPE_PRICE_ID - The ID of your subscription price in Stripe
  • STRIPE_PAYMENT_PRICE_ID - The ID of your one-time payment price in Stripe

For development, you can use Stripe's test mode keys. For production, make sure to use your live keys.

Apple Pay and Google Pay

The Stripe integration includes support for Apple Pay and Google Pay through Stripe's Payment Request Button. This allows for fast, secure mobile payments with minimal friction for users.

Webhooks

Webhooks are essential for handling asynchronous events from Stripe, such as successful payments, failed payments, and subscription lifecycle events. The kit includes pre-configured webhook handlers for all critical payment events.

Setting Up Webhooks

  1. Use the Stripe CLI to test webhooks locally:
    stripe listen --forward-to localhost:3000/api/webhooks/stripe
  2. For production, set up webhooks in the Stripe Dashboard pointing to your /api/webhooks/stripe endpoint.

Testing

Stripe provides test card numbers for testing different scenarios:

  • 4242 4242 4242 4242 - Successful payment
  • 4000 0000 0000 9995 - Failed payment
  • 4000 0000 0000 3220 - 3D Secure authentication

For testing subscriptions, you can use these test card numbers with any future expiry date, any 3-digit CVC, and any postal code.

Troubleshooting

  • If payments are failing, check your Stripe Dashboard for error messages
  • For webhook issues, use the Stripe CLI to debug webhook events
  • If Apple Pay or Google Pay isn't working, ensure your domain is properly configured in the Stripe Dashboard
  • For subscription issues, check the subscription status in the Stripe Dashboard