点数计费
PaymentKit 提供了一个灵活的系统，用于实现基于点数或预付费的计费。该模型允许您根据客户对服务的消耗量（例如 API 调用、数据存储或计算时间）向其收费。本指南将引导您完成整个工作流程，从定义计量内容到跟踪使用情况和管理客户余额。
点数计费系统建立在四个核心资源之上：
点数计费工作流#
下图说明了 PaymentKit 中基于点数的计费的典型生命周期：
1. 使用计量器定义用量#
计量器是一种资源，用于定义如何衡量特定服务的使用情况。您需要为要跟踪的每种不同类型的使用创建一个计量器。
使用 payment.meters.create() 方法创建一个新的计量器。
参数
Name | Type | Description |
|---|---|---|
|
| 计量器的人类可读名称（例如，“API 调用”）。 |
|
| 此计量器跟踪的事件的唯一标识符（例如，“api_calls”）。在报告使用情况时使用。 |
|
| 如何聚合使用事件。可以是 |
|
| 使用量的计量单位（例如，“次”、“字节”）。 |
|
| 关于计量器跟踪内容的可选描述。 |
示例
import payment from '@blocklet/payment-js';
async function createMeter() {
try {
const meter = await payment.meters.create({
name: 'API 调用',
event_name: 'api_calls',
aggregation_method: 'sum',
unit: '次',
description: '跟踪用户进行的 API 调用次数。'
});
console.log('计量器已创建：', meter);
} catch (error) {
console.error('创建计量器时出错：', error.message);
}
}
createMeter();响应示例
{
"id": "mtr_xxxxxxxxxxxxxx",
"object": "meter",
"name": "API 调用",
"event_name": "api_calls",
"aggregation_method": "sum",
"status": "active",
"unit": "次",
"description": "跟踪用户进行的 API 调用次数。",
"livemode": false,
"metadata": {},
"created_at": "2023-10-27T10:00:00.000Z",
"updated_at": "2023-10-27T10:00:00.000Z"
}2. 使用点数授予发放点数#
一旦有了计量器，您就可以向客户授予点数。点数授予代表添加到客户余额中的特定点数量。点数可以分为 paid（客户购买的）或 promotional（免费赠送的）。
使用 payment.creditGrants.create() 发放点数。
参数
Name | Type | Description |
|---|---|---|
|
| 接收点数的客户的 ID。 |
|
| 要授予的点数数量。 |
|
| 点数的货币。这必须与您的系统支持的货币相匹配。 |
|
| 授予的类别。必须是 |
|
| 点数授予的名称，供内部参考（例如，“新用户奖励”）。 |
|
| 可选。一个 Unix 时间戳，指示点数何时到期。 |
示例
import payment from '@blocklet/payment-js';
async function grantCredits() {
try {
const thirtyDaysFromNow = Math.floor(Date.now() / 1000) + (30 * 24 * 60 * 60);
const creditGrant = await payment.creditGrants.create({
customer_id: 'cus_xxx',
amount: '1000',
currency_id: 'pc_xxx',
category: 'promotional',
name: '新用户奖励点数',
expires_at: thirtyDaysFromNow
});
console.log('点数授予已创建：', creditGrant);
} catch (error) {
console.error('创建点数授予时出错：', error.message);
}
}
grantCredits();响应示例
{
"id": "cg_xxxxxxxxxxxxxx",
"object": "credit_grant",
"amount": "1000",
"currency_id": "pc_xxx",
"customer_id": "cus_xxx",
"category": "promotional",
"status": "granted",
"remaining_amount": "1000",
"expires_at": 1729852800,
"livemode": false,
"metadata": {},
"created_at": "2023-10-27T10:05:00.000Z",
"updated_at": "2023-10-27T10:05:00.000Z"
}3. 使用计量事件报告用量#
当您的客户使用您的服务时，您通过创建计量事件来报告他们的使用情况。PaymentKit 会自动从客户的点数余额中扣除相应的金额。
使用 payment.meterEvents.create() 报告使用情况。为每个事件提供唯一的 identifier 至关重要，以防止重复报告（幂等性）。
参数
Name | Type | Description |
|---|---|---|
|
| 此使用情况对应的计量器的 |
|
| 一个包含使用详情的对象。 |
|
| 消费该服务的客户的 ID。 |
|
| 要报告的使用量。 |
|
| 一个唯一的字符串，用于标识此特定使用事件并防止重复。 |
|
| 可选。使用发生时的 Unix 时间戳。默认为当前时间。 |
示例
import payment from '@blocklet/payment-js';
async function reportUsage() {
try {
const meterEvent = await payment.meterEvents.create({
event_name: 'api_calls',
payload: {
customer_id: 'cus_xxx',
value: '10'
},
identifier: `unique_event_${Date.now()}`,
timestamp: Math.floor(Date.now() / 1000)
});
console.log('计量事件已创建：', meterEvent);
} catch (error) {
console.error('创建计量事件时出错：', error.message);
}
}
reportUsage();响应示例
{
"id": "mevt_xxxxxxxxxxxxxx",
"event_name": "api_calls",
"payload": {
"customer_id": "cus_xxx",
"value": "10"
},
"identifier": "unique_event_1698372300000",
"timestamp": 1698372300,
"livemode": false,
"status": "completed",
"credit_consumed": "10",
"created_at": "2023-10-27T10:10:00.000Z",
"updated_at": "2023-10-27T10:10:00.000Z"
}4. 监控余额和历史记录#
您可以监控客户的点数余额并查看其交易历史，以了解其使用模式。
查询点数余额
使用 payment.creditGrants.summary() 获取客户可用和待处理点数的摘要，按货币分组。
import payment from '@blocklet/payment-js';
async function checkBalance() {
try {
const creditSummary = await payment.creditGrants.summary({
customer_id: 'cus_xxx'
});
console.log('点数摘要：', creditSummary);
} catch (error) {
console.error('获取点数摘要时出错：', error.message);
}
}
checkBalance();响应示例
{
"customer_id": "cus_xxx",
"total_balance": {
"pc_xxx": {
"currency_id": "pc_xxx",
"total_amount": "1000",
"available_amount": "990",
"pending_amount": "0",
"currency": {
"id": "pc_xxx",
"symbol": "CRDT",
"decimal": 18
}
}
}
}查看交易历史
使用 payment.creditTransactions.list() 检索客户所有点数交易的分页列表，包括授予、消耗和过期。
import payment from '@blocklet/payment-js';
async function listTransactions() {
try {
const transactions = await payment.creditTransactions.list({
customer_id: 'cus_xxx',
pageSize: 10
});
console.log('点数交易：', transactions.list);
} catch (error) {
console.error('列出点数交易时出错：', error.message);
}
}
listTransactions();响应示例
{
"count": 2,
"list": [
{
"id": "ctxn_xxxxxxxxxxxxxx",
"type": "consumption",
"amount": "-10",
"running_balance": "990",
"description": "API 调用用量",
"created_at": "2023-10-27T10:10:00.000Z"
},
{
"id": "ctxn_yyyyyyyyyyyyyy",
"type": "grant",
"amount": "1000",
"running_balance": "1000",
"description": "新用户奖励点数",
"created_at": "2023-10-27T10:05:00.000Z"
}
]
}通过遵循这些步骤，您可以成功实现一个完整的基于点数的计费系统。要探索每个函数的所有可用选项，请参阅详细的API 参考。要接收与点数相关事件（例如余额不足）的实时通知，请参阅 Webhooks 指南。