Stripe Provider

Overview

Stripe is the most popular payment processor, offering comprehensive features for both one-time and subscription payments. It's battle-tested, feature-rich, and trusted by millions of businesses worldwide.

Setup

1. Create a Stripe Account

1. Sign up at https://stripe.com
2. Complete your account setup
3. Navigate to the Dashboard

2. Get Your API Keys

1. Go to Developers → API keys in your Stripe Dashboard
2. You'll find two types of keys:
   • Secret key: Used in your backend (starts with sk_)

For Development:

• Use test mode keys (toggle "View test data" in the dashboard)
• Test keys start with pk_test_ and sk_test_

For Production:

• Use live mode keys
• Live keys start with pk_live_ and sk_live_

3. Create Products and Prices

1. Go to Products → Add product in your Stripe Dashboard
2. Create a product (e.g., "Pro Plan")
3. Add pricing:
   • For subscriptions: Choose "Recurring" and set the interval (monthly/yearly)
   • For one-time: Choose "One time"
   • Set the price amount and currency
4. After creating, copy the Price ID (starts with price_)

Example Products:

• Lifetime Plan: One-time payment → Price ID: price_1ABC123
• Pro Monthly: Recurring monthly → Price ID: price_2DEF456
• Pro Yearly: Recurring yearly → Price ID: price_3GHI789

4. Set Up Webhooks

Webhooks allow Stripe to notify your application about payment events.

For Local Development (using Stripe CLI):

1. Install the Stripe CLI: https://stripe.com/docs/stripe-cli
2. Login: stripe login
3. Forward webhooks to your local server:

   stripe listen --forward-to http://localhost:3000/api/webhooks/stripe

4. Copy the webhook signing secret (starts with whsec_) to your .env.local

For Production:

1. Go to Developers → Webhooks in Stripe Dashboard
2. Click Add endpoint
3. Set the endpoint URL: https://yourdomain.com/api/webhooks/stripe
4. Select events to listen to based on your payment types:

For One-Time Payments:

• checkout.session.completed (required) - Records the purchase when checkout completes

For Subscriptions:

• customer.subscription.created (required) - Creates subscription record
• customer.subscription.updated (required) - Updates subscription status/plan
• customer.subscription.deleted (required) - Removes subscription when canceled

If you use both payment types, select all events above.

5. Copy the Signing secret to your environment variables

5. Configure Environment Variables

Add these variables to your .env.local file:

# Stripe Secret Key (backend)
STRIPE_SECRET_KEY=sk_test_xxxxxxxxxxxxx

# Stripe Webhook Secret (for webhook verification)
STRIPE_WEBHOOK_SECRET=whsec_xxxxxxxxxxxxx

# Your Product Price IDs
NEXT_PUBLIC_PRICE_ID_LIFETIME=price_xxxxx
NEXT_PUBLIC_PRICE_ID_PRO_MONTHLY=price_xxxxx
NEXT_PUBLIC_PRICE_ID_PRO_YEARLY=price_xxxxx

Configuration

Set Stripe as your payment provider in config/index.ts:

export const config = {
  payments: {
    provider: "stripe",
    plans: {
      lifetime: {
        recommended: true,
        prices: [
          {
            type: "one-time",
            productId: process.env.NEXT_PUBLIC_PRICE_ID_LIFETIME as string,
            amount: 199,
            currency: "USD",
          },
        ],
      },
      pro: {
        recommended: false,
        prices: [
          {
            type: "subscription",
            productId: process.env.NEXT_PUBLIC_PRICE_ID_PRO_MONTHLY as string,
            amount: 19,
            currency: "USD",
            interval: "month",
          },
          {
            type: "subscription",
            productId: process.env.NEXT_PUBLIC_PRICE_ID_PRO_YEARLY as string,
            amount: 190,
            currency: "USD",
            interval: "year",
          },
        ],
      },
    },
  },
};

Testing

Stripe provides test card numbers for testing payments:

Successful Payment:

• Card: 4242 4242 4242 4242
• Any future expiry date (e.g., 12/34)
• Any 3-digit CVC

More test cards: https://stripe.com/docs/testing

Affiliate Tracking

With Rewardful

Add the referral ID as client_reference_id:

export const config = {
  affiliate: {
    enabled: true,
    provider: "rewardful",
  },
};

With PromoteKit

Add the referral ID to metadata:

export const config = {
  affiliate: {
    enabled: true,
    provider: "promotekit",
  },
};

The payment provider will automatically handle referral tracking based on your configuration.

Advanced Features

Trial Periods

Add trial periods to your subscriptions:

{
  type: "subscription",
  productId: process.env.NEXT_PUBLIC_PRO_PRICE_ID as string,
  amount: 19,
  currency: "USD",
  interval: "month",
  trialPeriodDays: 14, // 14-day free trial
}

Seat-Based Billing

Enable quantity-based pricing:

{
  type: "subscription",
  productId: process.env.NEXT_PUBLIC_ENTERPRISE_PRICE_ID as string,
  amount: 99,
  currency: "USD",
  interval: "month",
  seats: {
    min: 5,
    max: 100,
  },
}