Creem

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

设置

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

创建 Creem 账户

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

获取 API 密钥

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

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

设置 Webhook

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

• 进入到 Creem 控制台 > Developers > API & Webhooks，新建 Webhook
• 添加 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 设置，复制新建的 Webhook 签名密钥
• 将其保存到环境变量文件中作为 CREEM_WEBHOOK_SECRET

创建产品和价格计划

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

• 进入到 Creem 控制台 > Commerce > 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

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

# API Key 和 Webhook Secret
CREEM_API_KEY=creem_test_...
CREEM_WEBHOOK_SECRET=...

# 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,
      },
    },
  },
},

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

环境配置设置环境变量

---

开发环境

对于本地开发，推荐使用 hostc 将本地服务器暴露到公网，以便 Creem 能够发送 Webhook 事件：

npx hostc

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

更新 .env 环境变量

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

.env

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

更新 Google OAuth 凭据设置

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

• 前往 APIs & Services > Credentials
• 编辑您的 OAuth 客户端
• 在 Authorized JavaScript origins 中添加：https://xxxx.hostc.dev
• 在 Authorized redirect URIs 中添加：https://xxxx.hostc.dev/api/auth/callback/google

更新 Creem Webhook URL

将 Creem 控制台中的 Webhook URL 设置为临时域名：

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

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

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

生产环境

1. 进入到 Creem 控制台 > Developers > API & 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 仅用于数据同步。

客户门户

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

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

测试卡

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

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

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

最佳实践

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

参考资料

• Creem 文档

• Creem API 参考

• Creem Webhooks 指南

• Creem 注册教程

• Stripe

• AI