基于信用点的计费
基于信用点的计费是一种灵活的按需付费模式，非常适合使用量不固定的服务，例如 API 调用、数据存储或计算时间。客户消费他们已购买或获赠的信用点，而不是支付固定的周期性费用。
本指南将引导您完成使用 PaymentKit SDK 设置和管理基于信用点的计费系统的端到端流程。您将使用的核心组件包括：
- 计量器：定义和跟踪特定功能的使用情况。
- 信用点授予：向您的客户发放信用点。
- 计量事件：实时报告客户使用情况。
- 信用点交易：所有信用点活动的分类账，包括授予和消耗。
信用点计费工作流程#
下图说明了基于信用点的计费的完整生命周期，从设置到使用报告和余额监控。
第 1 步：创建计量器以跟踪使用情况#
计量器是一种跟踪特定功能消耗的资源。您可以定义要跟踪的事件、如何聚合使用情况（例如，所有值的总和）以及计量单位。
创建计量器
import payment from '@blocklet/payment-js';
async function setupMeter() {
try {
const meter = await payment.meters.create({
name: 'API 调用',
event_name: 'api.calls.v1',
aggregation_method: 'sum',
unit: 'calls',
description: '跟踪客户进行的 API 调用次数。'
});
console.log('计量器已创建：', meter.id);
return meter;
} catch (error) {
console.error('创建计量器时出错：', error.message);
}
}
setupMeter();在此示例中，我们创建了一个名为“API Calls”的计量器，用于监听名为 api.calls.v1 的事件。aggregation_method: 'sum' 告诉 PaymentKit 将所有报告事件的 value 相加，以计算总使用量。
第 2 步：向客户授予信用点#
有了计量器后，您需要给客户信用点以供消费。您可以将信用点作为促销奖励授予，或者在客户购买后授予。每次信用点授予都会指定金额、货币和所属客户。
授予促销信用点
import payment from '@blocklet/payment-js';
async function grantNewUserBonus(customerId, currencyId) {
try {
const thirtyDaysFromNow = Math.floor(Date.now() / 1000) + (30 * 24 * 60 * 60);
const creditGrant = await payment.creditGrants.create({
customer_id: customerId, // 例如，'cus_xxx'
currency_id: currencyId, // 例如，'pc_xxx'
amount: '1000',
name: '新用户奖励',
category: 'promotional', // 可以是 'paid' 或 'promotional'
expires_at: thirtyDaysFromNow
});
console.log('信用点授予已创建：', creditGrant.id);
return creditGrant;
} catch (error) {
console.error('创建信用点授予时出错：', error.message);
}
}
// grantNewUserBonus('cus_xxx', 'pc_xxx');此代码向客户授予 1000 点促销信用点，这些信用点将在 30 天后过期。分类为 paid 的信用点通常在 promotional 信用点之前使用。
第 3 步：使用计量事件报告使用情况#
当客户使用计量功能时，您的应用程序必须通过创建计量事件向 PaymentKit 报告。此事件应与您创建的计量器的 event_name 相匹配。
为防止因网络问题或重试导致重复报告使用情况，请务必为每个事件包含一个唯一的 identifier。PaymentKit 只会处理收到的具有给定标识符的第一个事件。
报告使用事件
import payment from '@blocklet/payment-js';
async function reportApiCall(customerId, subscriptionId) {
try {
const meterEvent = await payment.meterEvents.create({
event_name: 'api.calls.v1', // 必须与计量器的 event_name 匹配
payload: {
customer_id: customerId, // 'cus_xxx'
value: '10', // 要报告的使用量
subscription_id: subscriptionId, // 可选：与订阅关联
},
identifier: `unique_api_call_${Date.now()}` // 幂等性密钥
});
console.log('计量事件已报告：', meterEvent.id);
return meterEvent;
} catch (error) {
console.error('报告计量事件时出错：', error.message);
}
}
// reportApiCall('cus_xxx', 'sub_xxx');处理此事件时，PaymentKit 会自动查找客户的活动信用点授予，并从其余额中扣除 10 个信用点。
第 4 步：检查信用点余额#
您可以随时使用 summary 方法检查客户的剩余信用点余额。这对于在您的应用程序界面中显示余额非常有用。
检查信用点摘要
import payment from '@blocklet/payment-js';
async function checkCreditBalance(customerId) {
try {
const creditSummary = await payment.creditGrants.summary({
customer_id: customerId, // 'cus_xxx'
});
console.log('信用点摘要：', creditSummary);
return creditSummary;
} catch (error) {
console.error('获取信用点摘要时出错：', error.message);
}
}
// checkCreditBalance('cus_xxx');响应示例
{
"pc_xxx": { // currency_id
"paymentCurrency": {
"id": "pc_xxx",
"name": "Credit",
"symbol": "C",
"decimal": 2,
"type": "credit"
},
"totalAmount": "1000.00",
"remainingAmount": "990.00",
"grantCount": 1
}
}响应按货币分组，显示授予的总信用点和指定客户的剩余金额。
第 5 步：查看交易历史#
要查看客户所有信用点活动的详细审计日志（包括授予、消耗和过期），您可以列出他们的信用点交易。
列出信用点交易
import payment from '@blocklet/payment-js';
async function getTransactionHistory(customerId) {
try {
const transactions = await payment.creditTransactions.list({
customer_id: customerId, // 'cus_xxx'
pageSize: 10
});
console.log(`找到 ${transactions.total} 笔交易。`);
transactions.data.forEach(tx => {
console.log(`- ID: ${tx.id}, 类型: ${tx.type}, 金额: ${tx.amount}, 余额: ${tx.running_balance}`);
});
return transactions;
} catch (error) {
console.error('列出信用点交易时出错：', error.message);
}
}
// getTransactionHistory('cus_xxx');这提供了完整的历史记录，让您可以追踪客户信用点余额的每一次变动。
后续步骤#
现在您已经对基于信用点的计费工作流程有了全面的了解。有关每个组件的更详细信息，包括所有可用参数和方法，请参阅 API 参考文档。
要了解客户如何购买信用点或设置自动充值，请参阅信用点充值指南。