Creem

TanStarter 使用 Creem 进行支付管理，支持一次性支付和订阅支付。Creem 是一个面向独立开发者的 Merchant of Record（MoR）支付平台，内置全球税务合规（190+ 国家），无需自行处理 VAT/GST/销售税。

设置

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

创建 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
创建专业版订阅计划的产品：
- 点击创建产品
- 名称：专业版计划
- 描述：具有订阅价格的高级功能
- 添加月度价格：
  - 价格：$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
创建终身计划的产品：
- 点击创建产品
- 名称：终身计划
- 描述：终身访问的一次性支付
- 添加价格：
  - 价格：$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

# Product IDs
VITE_CREEM_PRODUCT_PRO_MONTHLY=prod_...
VITE_CREEM_PRODUCT_PRO_YEARLY=prod_...
VITE_CREEM_PRODUCT_LIFETIME=prod_...

更新网站配置

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

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

src/config/website.ts

payment: {
  enable: isPaymentEnabled,              // ← 自动：当 VITE_PAYMENT_PROVIDER 设置时为 true
  provider: isPaymentEnabled ? paymentProvider : undefined, // ← 自动：'creem'
  price: {
    plans: {
      free: {
        id: 'free',
        prices: [],
        isFree: true,
        isLifetime: false,
      },
      pro: {
        id: 'pro',
        prices: [
          {
            type: 'subscription',
            priceId: priceIds.proMonthly,  // ← 自动：来自 VITE_CREEM_PRODUCT_PRO_MONTHLY
            amount: 990,                   // 金额，单位为分（$9.90）
            currency: 'USD',
            interval: 'month',
          },
          {
            type: 'subscription',
            priceId: priceIds.proYearly,   // ← 自动：来自 VITE_CREEM_PRODUCT_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_CREEM_PRODUCT_LIFETIME
            amount: 19900,                  // 金额，单位为分（$199.00）
            currency: 'USD',
            allowPromotionCode: true,
          },
        ],
        isFree: false,
        isLifetime: true,
      },
    },
  },
},

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

环境配置

设置环境变量

核心功能

一次性支付成为终身会员功能
定期订阅支付（月度/年度）
支持免费试用期
内置全球税务合规（190+ 国家自动处理 VAT/GST/销售税）
订阅管理与客户门户集成
支付事件的 Webhook 处理
订阅状态的跟踪和验证功能
内置价格组件（表格、卡片、按钮）
安全支付操作的服务器端操作
多种价格计划支持（免费、专业版、终身制）
内置联盟营销和收益分成功能
自动许可证密钥生成和分发

开发环境

对于本地开发，您需要使用 ngrok 或类似工具将本地服务器暴露到公网，以便 Creem 能够发送 Webhook 事件：

ngrok http 3000

然后将 ngrok 提供的 HTTPS URL 作为 Webhook URL 添加到 Creem 控制台中：

进入到 Creem 控制台 > Developers > Webhooks
添加 Webhook URL：https://YOUR-NGROK-URL/api/webhooks/creem

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

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 请求头发送。

TanStarter 使用 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;
}

Webhook 重试机制

如果 Webhook 发送失败，Creem 会自动按照以下时间间隔进行重试：

30 秒后第一次重试
1 分钟后第二次重试
5 分钟后第三次重试
1 小时后第四次重试

您也可以在 Creem 控制台的 Developers 部分手动重新发送事件。

客户门户

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

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

测试卡

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

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

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

Creem vs Stripe

特性	Creem	Stripe
定位	Merchant of Record（MoR）	支付网关
税务合规	自动处理全球税务	需要自行配置
费率	3.9% + $0.40	2.9% + $0.30
退款处理	Creem 代为处理	需要自行处理
设置难度	简单，适合独立开发者	功能全面，配置灵活
微信/支付宝	不支持	支持

最佳实践

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

进入到 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
创建专业版订阅计划的产品：
- 点击创建产品
- 名称：专业版计划
- 描述：具有订阅价格的高级功能
- 添加月度价格：
  - 价格：$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
创建终身计划的产品：
- 点击创建产品
- 名称：终身计划
- 描述：终身访问的一次性支付
- 添加价格：
  - 价格：$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

# Product IDs
VITE_CREEM_PRODUCT_PRO_MONTHLY=prod_...
VITE_CREEM_PRODUCT_PRO_YEARLY=prod_...
VITE_CREEM_PRODUCT_LIFETIME=prod_...

更新网站配置

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

src/config/website.ts

payment: {
  enable: isPaymentEnabled,              // ← 自动：当 VITE_PAYMENT_PROVIDER 设置时为 true
  provider: isPaymentEnabled ? paymentProvider : undefined, // ← 自动：'creem'
  price: {
    plans: {
      free: {
        id: 'free',
        prices: [],
        isFree: true,
        isLifetime: false,
      },
      pro: {
        id: 'pro',
        prices: [
          {
            type: 'subscription',
            priceId: priceIds.proMonthly,  // ← 自动：来自 VITE_CREEM_PRODUCT_PRO_MONTHLY
            amount: 990,                   // 金额，单位为分（$9.90）
            currency: 'USD',
            interval: 'month',
          },
          {
            type: 'subscription',
            priceId: priceIds.proYearly,   // ← 自动：来自 VITE_CREEM_PRODUCT_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_CREEM_PRODUCT_LIFETIME
            amount: 19900,                  // 金额，单位为分（$199.00）
            currency: 'USD',
            allowPromotionCode: true,
          },
        ],
        isFree: false,
        isLifetime: true,
      },
    },
  },
},

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

环境配置

设置环境变量

核心功能

一次性支付成为终身会员功能
定期订阅支付（月度/年度）
支持免费试用期
内置全球税务合规（190+ 国家自动处理 VAT/GST/销售税）
订阅管理与客户门户集成
支付事件的 Webhook 处理
订阅状态的跟踪和验证功能
内置价格组件（表格、卡片、按钮）
安全支付操作的服务器端操作
多种价格计划支持（免费、专业版、终身制）
内置联盟营销和收益分成功能
自动许可证密钥生成和分发

开发环境

对于本地开发，您需要使用 ngrok 或类似工具将本地服务器暴露到公网，以便 Creem 能够发送 Webhook 事件：

ngrok http 3000

然后将 ngrok 提供的 HTTPS URL 作为 Webhook URL 添加到 Creem 控制台中：

进入到 Creem 控制台 > Developers > Webhooks
添加 Webhook URL：https://YOUR-NGROK-URL/api/webhooks/creem

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

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 请求头发送。

TanStarter 使用 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;
}

Webhook 重试机制

如果 Webhook 发送失败，Creem 会自动按照以下时间间隔进行重试：

30 秒后第一次重试
1 分钟后第二次重试
5 分钟后第三次重试
1 小时后第四次重试

您也可以在 Creem 控制台的 Developers 部分手动重新发送事件。

客户门户

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

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

测试卡

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

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

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

Creem vs Stripe

特性	Creem	Stripe
定位	Merchant of Record（MoR）	支付网关
税务合规	自动处理全球税务	需要自行配置
费率	3.9% + $0.40	2.9% + $0.30
退款处理	Creem 代为处理	需要自行处理
设置难度	简单，适合独立开发者	功能全面，配置灵活
微信/支付宝	不支持	支持

最佳实践

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

环境配置

目录

Creem

环境配置

目录