Herald

Creem 支付对接

面向 Realm Admin 的 Creem 对接操作指南。跟着做完，你的用户就能通过 Creem 完成订阅支付。

面向 Realm Admin 的 Creem 对接操作指南。跟着做完，你的用户就能通过 Creem 完成订阅支付。

给谁看

负责管理 Herald 计费配置的 Realm Admin。不需要写代码，全程在管理后台操作。

前置条件

  • Herald 管理后台可以正常访问，你有管理员账号
  • 已创建至少一个 Realm 和一个 Client App
  • 已在 Creem 注册账号，拿到 API Key（测试环境用 ck_test_ 开头的 key）

Creem 和 Stripe 的区别

Creem 没有类似 Stripe Product/Price 的 metadata 功能。这意味着 Herald 无法像 Stripe 那样从支付方商品自动导入 entitlement_key。Creem 的商品信息需要你在 Herald 中手动配置 entitlement 和积分策略。

其他流程（Checkout、Webhook、订阅投影）和 Stripe 基本一致。

核心概念

Herald 不维护本地商品目录。你在 Creem Dashboard 创建 Product，拿到 Product ID，然后在 Herald 里配置 Entitlement Mapping。用户付款后，Creem 通过 Webhook 通知 Herald，Herald 用 metadata 里的 herald_entitlement_key（写入 Checkout 请求，Creem 在 Webhook 中原样返回）找到对应的映射，创建订阅投影、发放积分。

数据流向：Creem Product → Herald Entitlement Mapping（手动配置） → 用户 Checkout → Creem Webhook（返回 herald_* metadata）→ Herald 订阅投影 + 积分发放

Step 1: 配置 Creem API Key 和 Webhook

在 Herald 管理后台配置 Creem 的连接信息。

  1. 在左侧菜单找到 Payment Providers，点击进入
  2. 找到 Creem，点击 Configure
  3. 填写配置表单：
    • API Key（必填）：填入在 Creem 后台拿到的 API Key，测试环境用 ck_test_ 开头的 key
    • Timeout（可选）：请求超时时间（秒）
    • Webhook Secret（必填）：Webhook 签名验证密钥，创建 Webhook 后获取，见下方
  4. 点击 Save

保存有效凭证后 Creem 即启用，没有单独的启用开关。

创建 Creem Webhook

  1. 打开 Creem Dashboard 的 Webhooks 页面

  2. 点击 Create Webhook

  3. 填写：

    • Name：Herald Webhook（随意取名）
    • URL：https://你的Herald域名/api/third/pay/{realmId}/creem/webhooks
      • 把 {realmId} 替换成你的 realm ID，比如 admin

  4. 选择事件——必须勾选以下 12 个，缺任何一个会导致对应的支付流程断裂：

结账事件

事件Herald 处理逻辑
checkout.completed验证结账 metadata，记录审计状态。订阅创建推迟到 subscription.paid 事件

订阅事件

事件Herald 处理逻辑
subscription.paid订阅首次支付或续费成功，创建订阅投影，发放积分
subscription.update订阅升降级处理，调整积分
subscription.canceled订阅取消（即时或期末取消），回收未使用积分
subscription.active订阅激活，同步订阅状态
subscription.trialing订阅试用，同步订阅状态
subscription.paused订阅暂停，同步订阅状态
subscription.past_due订阅逾期，同步订阅状态
subscription.scheduled_cancel订阅计划取消，同步订阅状态并设置到期时间
subscription.expired订阅过期，取消订阅并回收积分

退款与争议事件

事件Herald 处理逻辑
refund.created退款，按退款类型回收积分
dispute.created争议发起，标记订阅为争议状态
  1. 创建完成后复制 Signing secret，回到 Herald Payment Providers → Creem 配置，填入 Webhook Secret

测试环境和生产环境

Creem 的 API Key 前缀决定了请求发到哪里：

  • ck_test_ 开头：自动使用 Creem 测试环境 test-api.creem.io，不会产生真实扣款
  • 其他前缀：使用 Creem 生产环境 api.creem.io，会真实扣款

开发阶段用测试 key，上线前换成生产 key。

Step 2: 在 Creem 创建商品

在 Creem Dashboard 创建你的 Product，记下 Product ID（形如 prod_xxxxxxxx）。Creem 的商品价格等信息在 Creem 后台管理。

Herald 不会自动知道你在 Creem 创建了什么商品。下一步需要同步。

Step 3: 同步 Creem 商品到 Herald

  1. 在 Herald 管理后台左侧菜单点击 Entitlement Mappings
  2. 点击 Sync Provider Products 按钮
  3. 选择支付方 Creem
  4. 等待同步完成

同步完成后你会看到从 Creem 拉取的商品列表。每条记录包含 External Product ID、自动生成的 Entitlement Key（格式为 creem-{normalized_product_id}），以及它默认归属的积分账户（Realm 的注册接收池）。列表的主标签用产品名，缺失时回退到 External Product ID。

Creem 价格按原值展示。Creem 返回的价格本身就是显示值（字符串如 "9.99"），展示时直接用，不做 Stripe 那种最小货币单位整数（分）的除以 100 换算。币种跟随 Creem 返回值。两条换算分支（Stripe 与 Creem）是分开的，不会互相污染。

因为 Creem 没有 Product metadata，同步只能拉取商品 ID 和基本信息。entitlement_key 和积分策略需要手动配置。Creem Product 对象在 /v1/products/search 响应里没有原生 metadata 字段（Creem 的 metadata 是 checkout 会话级，不是 Product 级），所以 Herald 不为 Creem 同步 metadata，mapping 详情里 metadata 一栏按空处理，不伪造。计费周期如果 Creem 响应里有 billing_period（形如 every-month），前端做文案映射展示，缺失时显示"—"。

Step 4: 配置 Entitlement Mapping

这一步是 Creem 对接和 Stripe 的主要差异。Stripe 可以从 metadata 导入 entitlement_key，Creem 不行，必须在 Herald 中手动配置。

  1. 在 Entitlement Mappings 列表中，找到要配置的 Creem 映射
  2. 点击编辑，填写以下字段：
    • Entitlement Key（必填）：改成你能识别的名字，比如 pro-monthly。这个 key 在 SDK 查询、积分策略、Webhook 处理中都会用到
    • Billing Type：Recurring（订阅）或 OneTime（一次性购买）
    • Points Per Period：每个计费周期发放多少积分
    • Grant On Subscribe：首次订阅时是否发放积分
    • Validity Days：积分有效期（天），0 或不填表示永不过期
    • Enabled：是否启用。禁用后 Webhook 仍更新订阅投影，但不触发积分发放
  3. 点击保存

归属积分账户

每条映射必须挂在某个积分账户上。同步进来的映射默认挂在本 Realm 的注册接收池账户。如果这个套餐属于某条独立业务线，去 积分账户 页面把它挪到对应的积分账户。

积分账户决定了两件事：用户购买后积分进哪个池、哪些 Client App 能消费这些积分。积分账户的概念见计费架构。

Step 5: 用户支付流程

配置完成后，用户侧的流程如下。

  1. 用户在你的应用中选择套餐
  2. 你的应用调用 Herald 的 Checkout API（传入 entitlement_key、payment_provider=creem）
  3. Herald 查 Entitlement Mapping 找到 Creem 商品 ID
  4. Herald 调 Creem API 创建支付会话，metadata 写入 herald_entitlement_key、herald_user_id、herald_client_app_id、herald_realm_id、herald_billing_kind
  5. 返回 Creem 支付页面 URL
  6. 用户在 Creem 页面完成付款
  7. Creem 发 Webhook（checkout.completed → subscription.paid）
  8. Herald 从 metadata 解析 entitlement_key，创建订阅投影、发放积分
  9. 后续续费由 Creem 自动处理，发 subscription.paid 事件，Herald 发放续费积分

Creem 的 Webhook 会返回 Checkout 请求时写入的 metadata。Herald 靠这个来识别用户和 entitlement。

Step 6: 确认结果

查看 Entitlement Mapping 状态

  1. 在 Entitlement Mappings 页面，确认映射的 Enabled 状态和积分策略配置

查看订阅状态

  1. 在左侧菜单点击 Subscriptions，查看订阅投影列表
  2. 确认 entitlement_key、status、payment_provider 字段正确

查看变更历史

  1. 点击 Subscription History，查看订阅的完整变更时间线

Webhook 正常回调的话，状态会在几秒内更新。迟迟没变化，看下面的常见问题。

常见问题

Webhook 没收到

确保 Herald 部署的公网地址可以从 Creem 服务器访问。Webhook 端点地址格式：https://你的域名/api/third/pay/{realmId}/creem/webhooks

在 Creem Dashboard 的 Webhook 配置里检查 URL 是否正确。

套餐在应用里看不到

  1. Entitlement Mapping 的 Enabled 状态是否开启
  2. Creem API Key 是否已配置并启用
  3. 已执行过 Sync Provider Products

支付成功但订阅未激活

检查 Herald 日志里有没有收到 POST /api/third/pay/{realmId}/creem/webhooks 请求。

常见原因：

  • Creem Dashboard 里的 Webhook URL 配错了
  • Herald 服务器防火墙拦截了 Creem 的回调请求
  • SSL 证书有问题

"Creem not configured for realm" 报错

Step 1 的 API Key 没配好。检查 Payment Providers 页面 Creem 的配置。

同步失败

如果 Creem API 不可用导致同步失败，现有的映射数据不受影响，仍可正常使用。等 API 恢复后重试同步即可。

操作清单

  • Payment Providers 页面配置了 Creem（API Key 和 Webhook Secret 已填入并启用）
  • Creem Dashboard 创建了 Webhook 端点，12 个事件全部勾选
  • Webhook Secret 和 Creem 端点的 Signing secret 一致
  • 在 Creem 创建了 Product，记下了 Product ID
  • 在 Herald Entitlement Mappings 页面执行了 Sync Provider Products
  • 手动配置了 Entitlement Key 和积分策略（Creem 无法自动导入）
  • 映射状态为 Enabled
  • 用测试 Key 跑通了一次支付流程

On this page

给谁看前置条件Creem 和 Stripe 的区别核心概念Step 1: 配置 Creem API Key 和 Webhook创建 Creem Webhook结账事件订阅事件退款与争议事件测试环境和生产环境Step 2: 在 Creem 创建商品Step 3: 同步 Creem 商品到 HeraldStep 4: 配置 Entitlement Mapping归属积分账户Step 5: 用户支付流程Step 6: 确认结果查看 Entitlement Mapping 状态查看订阅状态查看变更历史常见问题Webhook 没收到套餐在应用里看不到支付成功但订阅未激活"Creem not configured for realm" 报错同步失败操作清单