支付

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

设置

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

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_...

import { clientEnv } from '@/env/client';

export const websiteConfig: WebsiteConfig = {
  // ...other config
  payment: {
    enable: true,
    provider: 'stripe',
    price: {
      plans: {
        free: {
          id: 'free',
          prices: [],
          isFree: true,
          isLifetime: false,
        },
        pro: {
          id: 'pro',
          prices: [
            {
              type: 'subscription',
              priceId: clientEnv.VITE_STRIPE_PRICE_PRO_MONTHLY!,
              amount: 990,
              currency: 'USD',
              interval: 'month',
              trialPeriodDays: 7,
            },
            {
              type: 'subscription',
              priceId: clientEnv.VITE_STRIPE_PRICE_PRO_YEARLY!,
              amount: 9900,
              currency: 'USD',
              interval: 'year',
              trialPeriodDays: 7,
            },
          ],
          isFree: false,
          isLifetime: false,
          popular: true,
        },
        lifetime: {
          id: 'lifetime',
          prices: [
            {
              type: 'one_time',
              priceId: clientEnv.VITE_STRIPE_PRICE_LIFETIME!,
              amount: 19900,
              currency: 'USD',
              allowPromotionCode: true,
            },
          ],
          isFree: false,
          isLifetime: true,
        },
      },
    },
  },
  // ...other config
}

核心功能

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

开发环境

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

pnpm install -g stripe/stripe-cli

登录到 Stripe：

stripe login

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

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

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

STRIPE_WEBHOOK_SECRET=whsec_...

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

生产环境

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
5. 创建后，点击 显示 查看 Webhook 签名密钥
6. 复制 Webhook 签名密钥（以 whsec_ 开头）并将其添加到您的环境变量中

自定义支付提供商

TanStarter 支持扩展新的支付提供商：

1. 在 src/payment/provider 目录中创建新的文件
2. 从 types.ts 实现 PaymentProvider 接口
3. 在 index.ts 中的 providerRegistry 注册新的提供商

新的支付服务提供商的示例实现：

import type {
  PaymentProvider,
  CreateCheckoutParams,
  CheckoutResult,
  CreatePortalParams,
  PortalResult,
} from '../types';

export class MyProvider implements PaymentProvider {
  getProviderName(): string {
    return 'my-provider';
  }

  public async createCheckout(params: CreateCheckoutParams): Promise<CheckoutResult> {
    // Create checkout session implementation
  }

  public async createCustomerPortal(params: CreatePortalParams): Promise<PortalResult> {
    // Create customer portal implementation
  }

  public async handleWebhookEvent(payload: string, signature: string): Promise<void> {
    // Handle webhook events implementation
  }
}

然后在 index.ts 中的 providerRegistry 注册新的提供商：

import { MyProvider } from './provider/my-provider';

const providerRegistry: Record<PaymentProviderName, ProviderFactory> = {
  stripe: () => new StripeProvider(),
  'my-provider': () => new MyProvider(),
};

测试卡

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

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

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

创建发票

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

// 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 文档中找到更多关于限制用户只能有一个订阅的信息。

最佳实践

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

参考资料

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

下一步

现在您了解了如何在 TanStarter 中使用支付，您可能想要探索这些相关功能：