Stripe

MkSaaS 支持 Stripe 进行支付管理，处理一次性支付和订阅支付功能。

设置Copy Anchor Link

MkSaaS 模板默认提供三种价格计划：免费计划、专业版订阅计划（月度/年度）和终身计划（一次性支付），按照以下步骤设置：

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

# 价格计划
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 = {
  // ...其他配置
  payment: {
    provider: 'stripe', // 要使用的支付提供商
  },
  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,
      },
    },
  },
  // ...其他配置
}

WebhooksCopy Anchor Link

Stripe Webhooks 对于处理异步事件（如成功支付和订阅更新）至关重要。

开发环境Copy Anchor Link

对于本地开发，使用 Stripe CLI 将事件转发到您的本地服务器：

请按照 Stripe 针对您操作系统提供的官方说明 安装 Stripe CLI，然后登录到 STRIPE_SECRET_KEY 所使用的同一测试模式账号：

登录到 Stripe：

stripe login

将事件转发到您的本地服务器：

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

Webhook 密钥在终端中打印，复制它并将其添加到环境变量文件中：

STRIPE_WEBHOOK_SECRET=whsec_...

您可以使用 Stripe CLI 触发测试事件，或在网站上测试事件：

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

也可以运行模板内置的 Stripe 测试模式真实流程：

pnpm e2e:stripe

自动化沙箱配置、服务器端口、环境文件优先级和数据库准备步骤见自动化测试及模板中的 tests/e2e/stripe/README.md。

支付确认与事件顺序Copy Anchor Link

invoice.paid 是 Stripe 支付成功的权威事件。 checkout.session.completed 只负责建立本地支付上下文，不会单独授予权益。

Stripe 不保证事件到达顺序。如果 invoice.paid 先到，MkSaaS 会在本次处理期间 重建 Checkout Session 并创建已支付记录。/payment 页面随后按 Checkout Session ID 和当前登录用户查找该记录。这也覆盖完全折扣的 Lifetime 订单：它有 Invoice， 但没有 PaymentIntent。

Webhook 响应与重试Copy Anchor Link

临时失败会返回 500，让 Stripe 自动重试；重复投递按幂等方式处理。

生产环境Copy Anchor Link

1. 进入到 Stripe 控制台 > 开发者 > Webhooks
2. 点击 添加端点
3. 输入 Webhook URL：https://YOUR-DOMAIN.com/api/webhooks/stripe
4. 选择要监听的事件：
   • invoice.paid
   • checkout.session.completed
   • customer.subscription.created
   • customer.subscription.updated
   • customer.subscription.deleted
   • charge.refunded
5. 创建后，点击 显示 查看 Webhook 签名密钥
6. 复制 Webhook 签名密钥（以 whsec_ 开头）并将其添加到您的环境变量中

UI 组件Copy Anchor Link

MkSaaS 包含用于处理支付的预构建 React 组件：

扩展新的支付提供商Copy Anchor Link

请查看支付，了解当前提供商接口、能力标记和 registry 注册方式。

测试卡Copy Anchor Link

要测试 Stripe 集成，请使用 Stripe 的测试模式和测试信用卡：

• 4242 4242 4242 4242 - 成功支付
• 4000 0000 0000 3220 - 需要 3D 安全认证
• 4000 0000 0000 9995 - 资金不足失败

您可以在 Stripe 文档中找到更多关于 Stripe 测试卡 的信息。

创建发票Copy Anchor Link

MkSaaS 已经为一次性支付配置了发票创建功能。

// 自动为一次性支付创建发票
checkoutParams.invoice_creation = {
  enabled: true,
};

如果您想自动发送已付发票，您可以在Customer emails settings中启用它，在Email customers about下，选择Successful payments。之后，您可以在 Stripe 控制台 > 发票中访问发票。

您可以在 Stripe 文档中找到更多关于自动发送已付发票的信息。

支付流程图Copy Anchor Link

这是完整的支付流程图，具体流程分析可以观看视频教程。

常见问答Copy Anchor Link

如何激活微信支付和支付宝？Copy Anchor Link

您可以在 Stripe 控制台 > Settings > Payment methods 中激活微信支付和支付宝。您可以在 Stripe 文档中找到更多关于微信支付和支付宝的信息。

如何限制用户只能有一个订阅？Copy Anchor Link

您可以在 Stripe 控制台 > Settings > Checkout and Payment Links > Subscriptions 中启用 Limit customers to 1 subscription，您可以在 Stripe 文档中找到更多关于限制用户只能有一个订阅的信息。

视频教程Copy Anchor Link

参考资料Copy Anchor Link

• Stripe 文档
• Stripe 支付对象概览
• Stripe 最佳实践

下一步Copy Anchor Link