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

生产环境

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

客户门户

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

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

测试卡

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

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

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

最佳实践

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