Stripe

Stripe is a widely used online payment platform. It supports many currencies and payment methods, and it is a solid default for products sold internationally.

Setup

1. Create a Stripe account

   • Go to the Stripe website
   • Sign up with your email
   • Complete identity verification (business or personal details)

2. Get API keys

   • Open the Stripe Dashboard
   • Go to Developers → API keys
   • Copy the publishable key and the secret key

3. Create products and prices

   • Create a product under Products
   • Add a price for each product
   • Copy the price ID. You will set it as stripePriceId

4. Configure the webhook (production)

   Local development: You can skip this step while testing locally. Use the Stripe CLI to forward webhooks. See the payment testing guide.

   Production:

   • Go to Developers → Webhooks
   • Add an endpoint: https://yourdomain.com/api/payment/webhook/stripe
   • Select the events the app handles:
     • checkout.session.completed
     • customer.subscription.updated
     • customer.subscription.deleted
     • charge.refunded
     • charge.dispute.created
   • Copy the webhook signing secret into STRIPE_WEBHOOK_SECRET

Environment variables

Add these to .env:

# Stripe
STRIPE_SECRET_KEY=sk_test_xxxxxxxx        # Secret key (use sk_live_ in production)
STRIPE_PUBLIC_KEY=pk_test_xxxxxxxx        # Publishable key (use pk_live_ in production)
STRIPE_WEBHOOK_SECRET=whsec_xxxxxxxx      # Webhook signing secret (the Stripe CLI prints one for local development)

Features

• Many currencies (USD, EUR, CNY, JPY, and others)
• One-time payments and subscriptions
• Cards, debit cards, and wallets
• Available to individuals and businesses

Get the price ID

1. Open the Stripe Dashboard
2. Go to Products → Product catalog
3. Create a product and set its price
4. Copy the price ID (it starts with price_)

Plan examples

Plans are typed objects on paymentConfig.plans. For Stripe, the billed amount and interval come from the Price in the Stripe Dashboard (stripePriceId). amount and duration are used for display and local calculations.

Subscription

monthly: {
  provider: 'stripe',
  id: 'monthly',
  // The billed period and price come from stripePriceId.
  // duration and amount here are for display and local calculations.
  amount: 10,
  currency: 'USD',
  duration: {
    months: 1,
    type: 'recurring'
  },
  stripePriceId: 'price_1RL2GgDjHLfDWeHDBHjoZaap',
  recommended: true,
  i18n: {
    'en': {
      name: 'Monthly Plan',
      description: 'Perfect for short-term projects',
      duration: 'month',
      features: ['All premium features', 'Priority support']
    }
  }
}

Lifetime (one-time)

lifetime: {
  provider: 'stripe',
  id: 'lifetime',
  amount: 999,
  currency: 'USD',
  recommended: true,
  duration: {
    months: 999999,             // Lifetime. months >= 9999 is treated as a lifetime plan
    type: 'one_time'
  },
  stripePriceId: 'price_1RL2IcDjHLfDWeHDMCmobkzb',
  i18n: {
    'en': {
      name: 'Lifetime',
      description: 'One-time payment, lifetime access',
      duration: 'lifetime',
      features: ['All premium features', 'Priority support', 'Free lifetime updates']
    }
  }
}

Back to Payment overview