Stripe

ShipSaaS 使用 Stripe 进行支付管理，支持一次性支付和订阅支付。

设置

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

创建 Stripe 账户

在 stripe.com 创建 Stripe 账户。

获取 API 密钥

从 Stripe 控制台获取您的 API 密钥：

进入到 Stripe 控制台 > Developers > API keys
复制密钥（注意：测试模式以 sk_test_ 开头，生产模式以 sk_live_ 开头）
将其保存到环境变量文件中作为 STRIPE_SECRET_KEY

设置 Webhook

设置 Webhook 并获取您的 Webhook 密钥：

进入到 Stripe 控制台 > Developers > Webhooks
点击 Add endpoint
输入 Webhook URL：https://YOUR-DOMAIN.com/api/webhooks/stripe
选择要监听的事件：
- invoice.paid
- checkout.session.completed
- customer.subscription.created
- customer.subscription.updated
- customer.subscription.deleted
点击 Reveal 查看 Webhook 签名密钥（以 whsec_ 开头）
将其保存到环境变量文件中作为 STRIPE_WEBHOOK_SECRET

创建产品和价格计划

在 Stripe 中创建产品并设置价格计划：

进入到 Stripe 控制台 > Product Catalog
创建专业版订阅计划的产品：
- 点击 Add product
- 名称：专业版计划
- 描述：具有订阅价格的高级功能
- 添加月度价格：
  - 点击 添加价格
  - 价格：$9.90（货币选择 USD）
  - 定期：月度
  - 保存并复制价格 ID（以 price_ 开头），这将用于 VITE_STRIPE_PRICE_PRO_MONTHLY
- 添加年度价格：
  - 点击 Add price
  - 价格：$99.00（货币选择 USD）
  - 定期：年度
  - 保存并复制价格 ID（以 price_ 开头），这将用于 VITE_STRIPE_PRICE_PRO_YEARLY
创建终身计划的产品：
- 点击 Add product
- 名称：终身计划
- 描述：终身访问的一次性支付
- 添加价格：
  - 价格：$199.00（货币选择 USD）
  - 类型：一次性
  - 保存并复制价格 ID（以 price_ 开头），这将用于 VITE_STRIPE_PRICE_LIFETIME

添加环境变量

添加以下环境变量：

.env

# 支付提供商
VITE_PAYMENT_PROVIDER=stripe

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

# Price plans
VITE_STRIPE_PRICE_PRO_MONTHLY=price_...
VITE_STRIPE_PRICE_PRO_YEARLY=price_...
VITE_STRIPE_PRICE_LIFETIME=price_...

更新网站配置

更新 src/config/website.ts 中的 payment 部分，配置价格计划 — 金额、货币、周期和计划元数据。enable、provider 和 priceId 字段会根据环境变量（VITE_PAYMENT_PROVIDER 和 VITE_STRIPE_PRICE_*）自动解析，无需硬编码。

您必须配置此部分，使其与您在 Stripe 中创建的产品和价格一致：

src/config/website.ts

payment: {
  enable: isPaymentEnabled,              // ← 自动：当 VITE_PAYMENT_PROVIDER 设置时为 true
  provider: isPaymentEnabled ? paymentProvider : undefined, // ← 自动：'stripe'
  price: {
    plans: {
      free: {
        id: 'free',
        prices: [],
        isFree: true,
        isLifetime: false,
      },
      pro: {
        id: 'pro',
        prices: [
          {
            type: 'subscription',
            priceId: priceIds.proMonthly,  // ← 自动：来自 VITE_STRIPE_PRICE_PRO_MONTHLY
            amount: 990,                   // 金额，单位为分（$9.90）
            currency: 'USD',
            interval: 'month',
          },
          {
            type: 'subscription',
            priceId: priceIds.proYearly,   // ← 自动：来自 VITE_STRIPE_PRICE_PRO_YEARLY
            amount: 9900,                  // 金额，单位为分（$99.00）
            currency: 'USD',
            interval: 'year',
          },
        ],
        isFree: false,
        isLifetime: false,
        popular: true,
      },
      lifetime: {
        id: 'lifetime',
        prices: [
          {
            type: 'one_time',
            priceId: priceIds.lifetime,     // ← 自动：来自 VITE_STRIPE_PRICE_LIFETIME
            amount: 19900,                  // 金额，单位为分（$199.00）
            currency: 'USD',
            allowPromotionCode: true,
          },
        ],
        isFree: false,
        isLifetime: true,
      },
    },
  },
},

如果您正在设置环境，现在可以回到环境配置文档并继续。本文档的其余部分可以稍后阅读。

环境配置设置环境变量

核心功能

一次性支付成为终身会员功能
定期订阅支付（月度/年度）
支持免费试用期
订阅管理与客户门户集成
支付事件的 Webhook 处理
订阅状态的跟踪和验证功能
内置价格组件（表格、卡片、按钮）
安全支付操作的服务器端操作
多种价格计划支持（免费、专业版、终身制）

开发环境

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

安装 Stripe CLI (macOS)：

brew install stripe/stripe-cli/stripe

或者使用 npm/bun 全局安装：

npm install -g stripe-cli

登录到 Stripe：

stripe login

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

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

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

STRIPE_WEBHOOK_SECRET=whsec_...

最后您可以在网站上进行支付操作，测试事件处理流程是否符合预期。

客户门户

Stripe 客户门户提供了一个托管门户，供客户管理他们的订阅。您可以自定义外观和可用功能。

进入到 Stripe 控制台 > Settings > Billing > Customer Portal
自定义客户门户界面显示的内容，例如，您可以添加一个自定义的 logo 和标题
点击 Save changes 保存门户配置

生产环境

进入到 Stripe 控制台 > 开发者 > Webhooks
点击 添加端点
输入 Webhook URL：https://YOUR-DOMAIN.com/api/webhooks/stripe
选择要监听的事件：

invoice.paid
checkout.session.completed
customer.subscription.created
customer.subscription.updated
customer.subscription.deleted

创建后，点击 显示 查看 Webhook 签名密钥
复制 Webhook 签名密钥（以 whsec_ 开头）并将其添加到您的环境变量中

测试卡

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

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

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

创建发票

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

src/payment/provider/stripe.ts

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

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

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

支付流程图

这是完整的支付流程图。

常见问答

如何激活微信支付和支付宝？

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

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

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

最佳实践

保护 API 密钥：永远不要在客户端代码中暴露您的 Stripe 密钥
验证 Webhook 签名：始终验证 Webhook 事件的签名
优雅处理错误：当支付失败时提供用户友好的错误消息
彻底测试 Webhooks：确保所有 Webhook 事件都得到正确处理