LogoMkSaaS文档
LogoMkSaaS文档
首页模板介绍代码库视频教程入门文档环境配置
网站配置

功能集成

数据库身份验证邮件邮件订阅存储
支付
StripeCreemWaffo Pancake
积分定时任务AI 功能统计分析通知验证码聊天框联盟营销

自定义

元数据字体主题图片国际化博客文档组件页面落地页用户管理密钥管理

代码库

IDE 设置项目结构格式化和代码检查更新代码库
X (Twitter)
支付

Creem

如何设置和使用 Creem 进行支付和订阅

MkSaaS 支持 Creem 进行支付管理，支持一次性支付和订阅支付。

设置

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

创建 Creem 账户

在 creem.io 创建 Creem 账户，注册无需信用卡。

获取 API 密钥

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

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

设置 Webhook

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

  • 进入 Creem 控制台 > Developers > Webhooks
  • 添加 Webhook URL：https://YOUR-DOMAIN.com/api/webhooks/creem
  • Creem 自动监听所有支付和订阅相关事件，包括：
    • checkout.completed
    • subscription.active
    • subscription.paid
    • subscription.update
    • subscription.canceled
    • subscription.scheduled_cancel
    • subscription.expired
    • subscription.past_due
    • subscription.paused
    • subscription.trialing
  • 复制 Webhook 签名密钥
  • 将其保存到环境变量文件中作为 CREEM_WEBHOOK_SECRET

创建产品和价格计划

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

  • 进入 Creem 控制台 > Products
  • 创建专业版订阅计划的产品：
    • 点击创建产品
    • 名称：Pro Plan
    • 描述：具有订阅价格的高级功能
    • 添加月度价格：
      • 价格：$9.90（货币选择 USD）
      • 计费类型：recurring
      • 计费周期：every-month
      • 保存并复制产品 ID（以 prod_ 开头），这将用于 VITE_CREEM_PRODUCT_PRO_MONTHLY
    • 添加年度价格（创建单独的产品）：
      • 价格：$99.00（货币选择 USD）
      • 计费类型：recurring
      • 计费周期：every-year
      • 保存并复制产品 ID（以 prod_ 开头），这将用于 VITE_CREEM_PRODUCT_PRO_YEARLY
  • 创建终身计划的产品：
    • 点击创建产品
    • 名称：Lifetime Plan
    • 描述：终身访问的一次性支付
    • 添加价格：
      • 价格：$199.00（货币选择 USD）
      • 计费类型：one_time
      • 保存并复制产品 ID（以 prod_ 开头），这将用于 VITE_CREEM_PRODUCT_LIFETIME

配置环境变量

添加以下环境变量：

.env
# 支付提供商
VITE_PAYMENT_PROVIDER=creem

CREEM_API_KEY=creem_test_...
CREEM_WEBHOOK_SECRET=...

# 设置为 'true' 以使用 Creem 测试 API，忽略或设置为 'false' 用于生产环境
# CREEM_DEBUG=true

# 产品 ID
VITE_CREEM_PRODUCT_PRO_MONTHLY=prod_...
VITE_CREEM_PRODUCT_PRO_YEARLY=prod_...
VITE_CREEM_PRODUCT_LIFETIME=prod_...

更新网站配置

更新 src/config/website.tsx 文件中的 payment 部分来配置价格计划 — 金额、货币、间隔和计划元数据。enable、provider 和 priceId 字段会自动从您的环境变量（VITE_PAYMENT_PROVIDER 和 VITE_CREEM_PRODUCT_*）解析，因此您无需硬编码。

您必须配置此部分以匹配您在 Creem 中创建的产品：

src/config/website.tsx
import { PaymentTypes, PlanIntervals } from '@/payment/types';

export const websiteConfig = {
  // ...其他配置
  payment: {
    enable: true,
    provider: 'creem',
  },
  price: {
    plans: {
      free: {
        id: 'free',
        prices: [],
        isFree: true,
        isLifetime: false,
        credits: {
          enable: true,
          amount: 50,
          expireDays: 30,
        },
      },
      pro: {
        id: 'pro',
        prices: [
          {
            type: PaymentTypes.SUBSCRIPTION,
            priceId: process.env.VITE_CREEM_PRODUCT_PRO_MONTHLY!,
            amount: 990,
            currency: 'USD',
            interval: PlanIntervals.MONTH,
          },
          {
            type: PaymentTypes.SUBSCRIPTION,
            priceId: process.env.VITE_CREEM_PRODUCT_PRO_YEARLY!,
            amount: 9900,
            currency: 'USD',
            interval: PlanIntervals.YEAR,
          },
        ],
        isFree: false,
        isLifetime: false,
        popular: true,
        credits: {
          enable: true,
          amount: 1000,
          expireDays: 30,
        },
      },
      lifetime: {
        id: 'lifetime',
        prices: [
          {
            type: PaymentTypes.ONE_TIME,
            priceId: process.env.VITE_CREEM_PRODUCT_LIFETIME!,
            amount: 19900,
            currency: 'USD',
            allowPromotionCode: true,
          },
        ],
        isFree: false,
        isLifetime: true,
        credits: {
          enable: true,
          amount: 1000,
          expireDays: 30,
        },
      },
    },
  },
  // ...其他配置
}

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

环境配置

设置环境变量

核心功能

  • 一次性支付获取终身会员
  • 循环订阅支付（月度/年度）
  • 免费试用周期支持
  • 内置全球税务合规（自动处理 190+ 国家/地区的增值税/消费税/销售税）
  • 订阅管理与客户门户集成
  • Webhook 处理支付事件
  • 订阅状态跟踪和验证
  • 内置定价组件（表格、卡片、按钮）
  • 服务器端操作确保支付安全
  • 多定价计划支持（免费、专业版、终身版）
  • 内置推荐计划和收入分成
  • 自动生成和分发许可证密钥

开发

对于本地开发，我们建议使用 hostc 将本地服务器暴露到互联网，以便 Creem 发送 webhook 事件：

npx hostc

hostc 会为您生成一个临时域名（例如 https://xxxx.hostc.dev）。由于 Creem 需要通过 webhooks 与您的本地服务器通信，您需要在以下三个地方更新临时域名：

更新 .env 环境变量

编辑您的 .env 文件，添加或更新以下变量：

.env
# 将临时域名添加到环境变量
NEXT_PUBLIC_APP_URL=https://xxxx.hostc.dev

更新 Google OAuth 凭据

如果您的应用程序使用 Google OAuth 登录，您需要在 Google Cloud Console 更新授权重定向 URI：

  • 进入 APIs & Services > Credentials
  • 编辑您的 OAuth 客户端
  • 将 https://xxxx.hostc.dev 添加到 Authorized JavaScript origins
  • 将 https://xxxx.hostc.dev/api/auth/callback/google 添加到 Authorized redirect URIs

更新 Creem Webhook URL

将 Creem 控制台 webhook URL 设置为临时域名：

  • 进入 Creem 控制台 > Developers > API & Webhooks
  • 添加 Webhook URL：https://xxxx.hostc.dev/api/webhooks/creem

完成上述配置后，您可以在网站上进行支付操作，以测试事件处理流程是否正常工作。

演示视频：https://cdn.mksaas.com/mksaas/video/mksaas-creem-payment.mp4

Creem 提供完整的测试环境。当使用以 creem_test_ 开头的 API 密钥时，所有操作都在沙盒中运行，不会产生真实交易。

生产环境

  1. 进入 Creem 控制台 > Developers > Webhooks
  2. 添加生产 Webhook URL：https://YOUR-DOMAIN.com/api/webhooks/creem
  3. 将 API 密钥从测试密钥（creem_test_）切换到生产密钥（creem_live_）
  4. 确保您的环境变量已使用生产密钥和产品 ID 更新

Webhook 事件

Creem 支持以下 webhook 事件：

事件描述
checkout.completed结账会话完成
subscription.active新订阅创建（仅用于同步）
subscription.paid订阅支付成功（用于激活访问权限）
subscription.update订阅更新（计划变更、周期续费）
subscription.canceled订阅取消
subscription.scheduled_cancel订阅被标记为在计费周期结束时取消
subscription.past_due支付失败，订阅等待重试
subscription.expired计费周期结束但未付款
subscription.trialing订阅进入试用周期
subscription.paused订阅暂停

Creem 建议使用 subscription.paid 事件来激活用户访问权限，而不是 subscription.active。subscription.active 事件仅用于数据同步。

Webhook 签名验证

Creem 使用 HMAC-SHA256 算法对 webhook 请求进行签名。签名通过 creem-signature 请求标头发送。

MkSaaS 使用 Web Crypto API 进行签名验证（兼容 Cloudflare Workers）：

src/payment/provider/creem.ts
async function verifySignature(payload: string, signature: string, secret: string): Promise<boolean> {
  const encoder = new TextEncoder();
  const key = await crypto.subtle.importKey(
    'raw',
    encoder.encode(secret),
    { name: 'HMAC', hash: 'SHA-256' },
    false,
    ['sign']
  );

  const signatureBuffer = await crypto.subtle.sign('HMAC', key, encoder.encode(payload));
  const computed = Array.from(new Uint8Array(signatureBuffer))
    .map((b) => b.toString(16).padStart(2, '0'))
    .join('');

  return computed === signature;
}

客户门户

每次成功支付后，您的客户将收到一封包含客户门户链接的电子邮件。门户允许他们：

  • 查看订阅详情
  • 管理订阅（升级、暂停、取消）
  • 查看支付历史
  • 更新支付方式

测试卡

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

  • 4242 4242 4242 4242 - 成功支付
  • 4000 0000 0000 0002 - 支付失败

当使用测试模式（以 creem_test_ 开头的 API 密钥）时，所有交易都在沙盒环境中运行，不会产生真实费用。

最佳实践

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

参考资料

  • Creem 文档
  • Creem API 参考
  • Creem Webhooks 指南
  • Creem 注册教程

Stripe

如何设置和使用 Stripe 处理支付和订阅

Waffo Pancake

如何设置和使用 Waffo Pancake 处理支付和订阅

目录

设置创建 Creem 账户获取 API 密钥设置 Webhook创建产品和价格计划配置环境变量更新网站配置核心功能开发更新 .env 环境变量更新 Google OAuth 凭据更新 Creem Webhook URL生产环境Webhook 事件Webhook 签名验证客户门户测试卡最佳实践参考资料