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 密钥时，所有操作都在沙盒中运行，不会产生真实交易。

生产环境

进入 Creem 控制台 > Developers > Webhooks
添加生产 Webhook URL：https://YOUR-DOMAIN.com/api/webhooks/creem
将 API 密钥从测试密钥（creem_test_）切换到生产密钥（creem_live_）
确保您的环境变量已使用生产密钥和产品 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 密钥）时，所有交易都在沙盒环境中运行，不会产生真实费用。

最佳实践

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

参考资料

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

更新网站配置

您必须配置此部分以匹配您在 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 密钥时，所有操作都在沙盒中运行，不会产生真实交易。

生产环境

进入 Creem 控制台 > Developers > Webhooks
添加生产 Webhook URL：https://YOUR-DOMAIN.com/api/webhooks/creem
将 API 密钥从测试密钥（creem_test_）切换到生产密钥（creem_live_）
确保您的环境变量已使用生产密钥和产品 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 密钥）时，所有交易都在沙盒环境中运行，不会产生真实费用。

最佳实践

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

环境配置

目录

Creem

环境配置

目录