Stripe

MkSaaS supports Stripe for payment management, handling both one-time payments and recurring subscriptions.

SetupCopy Anchor Link

MkSaaS boilerplate uses three price plans by default: Free plan, Pro subscription plan (monthly/yearly), and Lifetime plan (one-time payment), follow these steps to set up Stripe integration:

STRIPE_SECRET_KEY=sk_test_...
STRIPE_WEBHOOK_SECRET=whsec_...

# Price plans
NEXT_PUBLIC_STRIPE_PRICE_PRO_MONTHLY=price_...
NEXT_PUBLIC_STRIPE_PRICE_PRO_YEARLY=price_...
NEXT_PUBLIC_STRIPE_PRICE_LIFETIME=price_...

import { PaymentTypes, PlanIntervals } from '@/payment/types';

export const websiteConfig = {
  // ...other config
  payment: {
    provider: 'stripe', // Payment provider to use
  },
  price: {
    plans: {
      free: {
        id: 'free',
        prices: [],
        isFree: true,
        isLifetime: false,
      },
      pro: {
        id: 'pro',
        prices: [
          {
            type: PaymentTypes.SUBSCRIPTION,
            priceId: process.env.NEXT_PUBLIC_STRIPE_PRICE_PRO_MONTHLY!,
            amount: 990,
            currency: 'USD',
            interval: PlanIntervals.MONTH,
          },
          {
            type: PaymentTypes.SUBSCRIPTION,
            priceId: process.env.NEXT_PUBLIC_STRIPE_PRICE_PRO_YEARLY!,
            amount: 9900,
            currency: 'USD',
            interval: PlanIntervals.YEAR,
          },
        ],
        isFree: false,
        isLifetime: false,
        popular: true,
      },
      lifetime: {
        id: 'lifetime',
        prices: [
          {
            type: PaymentTypes.ONE_TIME,
            priceId: process.env.NEXT_PUBLIC_STRIPE_PRICE_LIFETIME!,
            amount: 19900,
            currency: 'USD',
            allowPromotionCode: true,
          },
        ],
        isFree: false,
        isLifetime: true,
      },
    },
  },
  // ...other config
}

WebhooksCopy Anchor Link

Stripe Webhooks are essential for handling asynchronous events like successful payments and subscription updates.

DevelopmentCopy Anchor Link

For local development, use the Stripe CLI to forward events to your local server:

Install the Stripe CLI using Stripe's official instructions for your operating system, then log in to the same Test Mode account used by STRIPE_SECRET_KEY:

Login to Stripe:

stripe login

Forward events to your local server:

stripe listen \
  --skip-update \
  --events checkout.session.completed,customer.subscription.created,customer.subscription.updated,customer.subscription.deleted,invoice.paid,charge.refunded \
  --forward-to http://localhost:3000/api/webhooks/stripe

The Webhook secret is printed in the terminal. Copy it and add it to your environment variables file:

STRIPE_WEBHOOK_SECRET=whsec_...

You can trigger test events using the Stripe CLI, or test events on the website:

stripe trigger invoice.paid
stripe trigger checkout.session.completed
stripe trigger customer.subscription.created
stripe trigger customer.subscription.updated
stripe trigger customer.subscription.deleted
stripe trigger charge.refunded

You can also run the real Stripe Test Mode flow included with the template:

pnpm e2e:stripe

For automated sandbox setup, server ports, environment-file precedence, and database prerequisites, see Automated Testing and tests/e2e/stripe/README.md in the template.

Payment Confirmation and Event OrderingCopy Anchor Link

invoice.paid is the authority for a successful Stripe payment. checkout.session.completed creates the local payment context, but does not grant access by itself.

Stripe does not guarantee event order. If invoice.paid arrives first, MkSaaS reconstructs the Checkout Session and creates the paid row during that delivery. The /payment page then finds the row by Checkout Session ID and signed-in user. This also supports a fully discounted Lifetime checkout, which has an Invoice but no PaymentIntent.

Webhook Responses and RetriesCopy Anchor Link

Temporary failures return 500 so Stripe can retry. Duplicate deliveries are handled idempotently.

ProductionCopy Anchor Link

1. Go to the Stripe Dashboard > Developers > Webhooks
2. Click Add endpoint
3. Enter Webhook URL: https://YOUR-DOMAIN.com/api/webhooks/stripe
4. Select the events to listen for:
   • invoice.paid
   • checkout.session.completed
   • customer.subscription.created
   • customer.subscription.updated
   • customer.subscription.deleted
   • charge.refunded
5. After creating, click Reveal to view your Webhook Signing Secret
6. Copy the Webhook secret (starts with whsec_) and add it to your environment variables

UI ComponentsCopy Anchor Link

MkSaaS includes pre-built React components for handling payments:

Extending New Payment ProvidersCopy Anchor Link

See Payment for the current provider interface, capability flags, and registry pattern.

Testing CardsCopy Anchor Link

For testing Stripe integration, use Stripe's test mode and test credit cards:

• 4242 4242 4242 4242 - Successful payment
• 4000 0000 0000 3220 - 3D Secure authentication required
• 4000 0000 0000 9995 - Insufficient funds failure

You can find more information about Stripe test cards in the Stripe documentation.

InvoicesCopy Anchor Link

MkSaaS has already configured the invoice creation for one-time payments.

// Automatically create an invoice for the one-time payment
checkoutParams.invoice_creation = {
  enabled: true,
};

If you want to automatically send paid invoices, you can enable it in your Customer emails settings, under Email customers about, select Successful payments. After that, you can access the invoices in the Stripe Dashboard > Invoices.

You can find more information about Automatically send paid invoices in the Stripe documentation.

DiagramCopy Anchor Link

This is the diagram of the payment process, you can watch the video tutorial for more details.

FAQCopy Anchor Link

How to activate WeChatPay and Alipay?Copy Anchor Link

You can activate WeChatPay and Alipay in the Stripe Dashboard > Settings > Payment methods. You can find more information about WeChat Pay and Alipay in the Stripe documentation.

How to limit users to only one subscription?Copy Anchor Link

You can enable Limit customers to 1 subscription in the Stripe Dashboard > Settings > Checkout and Payment Links > Subscriptions. You can find more information about Limit customers to one subscription in the Stripe documentation.

Video TutorialCopy Anchor Link

ReferenceCopy Anchor Link

• Stripe Documentation
• Stripe Payment Objects Overview
• Stripe Best Practices

Next StepsCopy Anchor Link