Creem

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

设置Copy Anchor Link

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

# 支付提供商
NEXT_PUBLIC_PAYMENT_PROVIDER=creem

CREEM_API_KEY=creem_test_...
CREEM_WEBHOOK_SECRET=...

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

# 产品 ID
NEXT_PUBLIC_CREEM_PRODUCT_PRO_MONTHLY=prod_...
NEXT_PUBLIC_CREEM_PRODUCT_PRO_YEARLY=prod_...
NEXT_PUBLIC_CREEM_PRODUCT_LIFETIME=prod_...

import { PaymentTypes, PlanIntervals } from '@/payment/types';

export const websiteConfig = {
  // ...其他配置
  payment: {
    provider: paymentProvider,
  },
  price: {
    plans: {
      free: {
        id: 'free',
        prices: [],
        isFree: true,
        isLifetime: false,
      },
      pro: {
        id: 'pro',
        prices: [
          {
            type: PaymentTypes.SUBSCRIPTION,
            priceId: priceIds.proMonthly,
            amount: 990,
            currency: 'USD',
            interval: PlanIntervals.MONTH,
          },
          {
            type: PaymentTypes.SUBSCRIPTION,
            priceId: priceIds.proYearly,
            amount: 9900,
            currency: 'USD',
            interval: PlanIntervals.YEAR,
          },
        ],
        isFree: false,
        isLifetime: false,
        popular: true,
      },
      lifetime: {
        id: 'lifetime',
        prices: [
          {
            type: PaymentTypes.ONE_TIME,
            priceId: priceIds.lifetime,
            amount: 19900,
            currency: 'USD',
            allowPromotionCode: true,
          },
        ],
        isFree: false,
        isLifetime: true,
      },
    },
  },
  // ...其他配置
}

核心功能Copy Anchor Link

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

开发Copy Anchor Link

保持应用使用正常的本地地址，只通过 HTTPS 隧道接收 Webhook。先启动 MkSaaS， 再在另一个终端用 Cloudflared 暴露 3000 端口：

pnpm dev

# 在第二个终端运行
cloudflared --config /dev/null tunnel \
  --url http://localhost:3000 \
  --no-autoupdate \
  --protocol quic

在 Creem 控制台切换到测试模式，将生成的地址注册为 https://xxxx.trycloudflare.com/api/webhooks/creem。继续保持 NEXT_PUBLIC_BASE_URL=http://localhost:3000；隧道只用于接收 Creem 的 Webhook。 Creem 会把浏览器直接带回 Billing 页面，签名 Webhook 在后台更新用户权益。

模板还包含 Creem 测试模式的真实 E2E 流程：

pnpm e2e:creem

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

自动化沙箱配置、服务器端口、环境文件优先级和数据库准备步骤见自动化测试及模板中的 tests/e2e/creem/README.md。

生产环境Copy Anchor Link

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

Webhook 事件Copy Anchor Link

Creem 支持以下 webhook 事件：

只有 subscription.canceled 是终态。过期或逾期订阅在后续支付成功后仍可恢复。

Webhook 响应与重试Copy Anchor Link

临时失败会返回 500，让 Creem 自动重试。处理器保持幂等，重复投递不会创建 重复支付记录。

Webhook 签名验证Copy Anchor Link

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

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

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;
}

客户门户Copy Anchor Link

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

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

测试卡Copy Anchor Link

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

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

最佳实践Copy Anchor Link

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

参考资料Copy Anchor Link

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