WSO2 是否支持 Prepaid 和 Postpaid 计费模式？

2026-10-24支付小周

结论

WSO2 API Manager 可以负责 API 发布、订阅、鉴权、限流和用量采集，但它不是一套完整的 Prepaid（预付费）或 Postpaid（后付费）计费系统。

部分 WSO2 API Manager 版本或部署形态支持 monetization 扩展，可以将订阅套餐和用量数据交给外部计费平台处理。具体能力和接口因版本而异。余额管理、扣费、账单、税务、支付失败重试和退款等功能，通常仍需接入专业计费系统或自行开发。

实际部署时，可以这样分工：

WSO2 API Manager 负责 API 管理和用量控制。
外部计费系统负责预付余额、后付账单和支付。
两套系统通过事件、用量记录或自定义网关策略连接。

WSO2 能提供什么

在商业化 API 场景中，WSO2 API Manager 通常可以提供这些基础能力：

管理 API 产品和订阅。
使用 OAuth 2.0、JWT、API Key 等方式控制访问。
按订阅或应用配置限流策略。
记录请求次数、响应状态、调用方等用量数据。
在配额用尽、账户欠费或订阅失效后暂停访问。
通过扩展点接入外部 monetization 或 billing 服务。

这些功能回答的是谁能调用 API、能调用多少次，以及实际调用了多少次，并不等同于财务计费。

一套完整的计费系统还要处理：

预付费账户充值和余额扣减。
后付费账期、账单生成和自动收款。
阶梯价格、最低消费、封顶价格和免费额度。
货币精度、税费、折扣和退款。
支付失败重试、对账和坏账处理。
发票及当地合规要求。

Prepaid 的实现方式

预付费模式需要一套可靠的账户余额或额度账本。基本流程如下：

用户完成充值。
支付平台通过 webhook 通知计费服务。
计费服务验证通知的真实性，再增加账户余额。
API 请求到达网关时，系统检查余额或可用额度。
请求成功后，根据实际用量扣费。
余额不足时，禁用订阅、收紧限流策略，或由网关拒绝请求。

扣费必须是原子操作。不能先查询余额再更新，否则并发请求可能造成余额透支。例如，可以在数据库中执行条件更新：

UPDATE billing_account
SET balance = balance - :cost
WHERE account_id = :account_id
  AND balance >= :cost;

如果受影响的行数为 0，说明余额不足或账户不存在，此次计费操作应被拒绝。

下面是一个简化的扣费接口：

app.post("/billing/debit", async (req, res) => {
  const { accountId, requestId, cost } = req.body;

  const existing = await ledger.findByRequestId(requestId);
  if (existing) {
    return res.json(existing);
  }

  const result = await accounts.debitIfSufficient(
    accountId,
    cost,
    requestId
  );

  if (!result.success) {
    return res.status(402).json({
      code: "INSUFFICIENT_BALANCE",
      message: "Prepaid balance is insufficient"
    });
  }

  res.json({
    requestId,
    charged: cost,
    remainingBalance: result.remainingBalance
  });
});

requestId 应全局唯一，确保请求重试时不会重复扣费。

有些 API 只有在处理完成后才能确定最终成本，例如按 token、流量或执行时间计费。这类场景可以采用“预授权加结算”模式：

请求开始前冻结预计费用。
请求结束后计算实际费用。
从冻结金额中结算。
释放剩余金额，或补扣差额。

Postpaid 的实现方式

后付费模式通常不必在每次请求前检查余额，而是持续记录用量，并在账期结束时汇总计费：

为每个订阅配置价格计划和账期。
采集成功调用次数或其他计费指标。
将用量记录写入不可重复消费的计量流水。
在账期结束时汇总费用。
创建账单，并调用支付平台收款。
对逾期账户采取提醒、限流或停用措施。

用量事件可以采用以下结构：

{
  "eventId": "01J7EXAMPLE9KQ2",
  "requestId": "req-7bfe21",
  "subscriptionId": "sub-1042",
  "apiId": "weather-api",
  "operation": "GET /forecast",
  "quantity": 1,
  "occurredAt": "2026-09-01T08:30:00Z",
  "status": "succeeded"
}

消费事件时，应基于 eventId 或 requestId 建立唯一约束：

INSERT INTO usage_event (
  event_id,
  request_id,
  subscription_id,
  api_id,
  operation,
  quantity,
  occurred_at
)
VALUES (
  :event_id,
  :request_id,
  :subscription_id,
  :api_id,
  :operation,
  :quantity,
  :occurred_at
)
ON CONFLICT (event_id) DO NOTHING;

如果采用“免费额度加超额单价”的简单模型，账单金额可以这样计算：

billable_quantity = max(0, total_quantity - free_quantity)
amount = base_fee + billable_quantity × unit_price

阶梯定价、套餐切换和按比例计费更为复杂，适合交给成熟的 billing engine 处理。

如何与 WSO2 集成

可用的扩展点取决于 WSO2 API Manager 的版本和部署方式，实施前需要查看对应版本的官方文档。常见的集成方式有：

从 WSO2 的分析数据或用量事件中提取计费记录。
在网关中加入自定义策略，调用余额检查服务。
由业务后端在请求完成后发送用量事件。
由计费服务根据账户状态启用或禁用订阅。
将商业套餐映射到 WSO2 的订阅层级和限流策略。

计费事件适合通过 Kafka 或 RabbitMQ 等异步消息系统传递。这样即使计费平台暂时不可用，API 请求也不一定要同步失败。

Prepaid 场景有所不同。如果业务绝对不允许透支，就必须在放行请求前同步检查余额或预留额度。这时需要在计费准确性、可用性和请求延迟之间作出权衡。

注意事项

不要直接按网关收到的所有请求收费

重试、鉴权失败、限流拒绝和后端异常未必应该收费。需要先定义明确的计费点，例如：

网关接受请求时收费。
后端返回成功响应时收费。
业务交易实际完成时收费。
按响应字节、计算时长或 token 用量收费。

如果 API 涉及业务事务，通常应以业务后端确认交易完成的事件作为最终计费依据。

金额不要使用浮点数

金额应使用最小货币单位或高精度十进制类型：

const amountInCents = 199; // ¥1.99 或 $1.99，取决于账户币种

不要使用 float 或 JavaScript 浮点数直接累计财务金额。

必须保证幂等性

网关、消息系统和 webhook 都可能重试。充值、扣费和用量入账必须带有唯一业务标识，并在数据库中建立唯一约束。

保留独立账本

不要只在账户表中保存余额。至少还要记录每次充值、冻结、扣费、退款和调整，方便审计与对账。

先确认版本能力

不同 WSO2 版本、产品形态和许可证提供的 monetization 能力可能不同。确定技术方案前，需要确认当前版本是否具备用量导出、扩展策略、订阅管理接口和外部计费集成能力。一个版本的示例不能直接套用到另一个版本。

WSO2 本身不是完整的 Prepaid/Postpaid 计费平台，但仍然可以用于这类系统。比较稳妥的分工是由 WSO2 管理 API，由专门的 billing service 处理财务计费，再通过可靠的用量事件和账户状态同步将两者连接起来。