自定义通知处理指南
Payment Kit 支持应用方自行处理通知，提供两种配置方式。
方案一：订阅级别控制#
在创建 checkoutSession 时，通过 subscription_data.notification_settings 配置通知处理方式。
const checkoutSession = await payment.checkout.sessions.create({
mode: 'subscription',
line_items: [{ price_id: 'your_price_id', quantity: 1 }],
subscription_data: {
notification_settings: {
self_handle: true, // 启用自定义处理
include_events: ['customer.subscription.started'] // 指定需要处理的事件
}
}
});方案二：全局控制#
通过 settings API 创建全局通知配置。
// 1. 创建全局的通知配置
const setting = await payment.settings.create({
type: 'notification',
mountLocation: 'your.app.id', // 使用你的应用 ID,或者自定义全局变量
description: '自定义通知配置',
componentDid: '', // 选填，应用did
settings: {
self_handle: true, // 启用自定义处理
include_events: [
'customer.subscription.started',
'customer.subscription.renewed'
]
}
});
// 2.在创建 checkoutSession 时关联配置
const checkoutSession = await payment.checkout.sessions.create({
mode: 'subscription',
line_items: [{ price_id: 'your_price_id', quantity: 1 }],
metadata: {
setting_id: setting.id // 关联配置 ID， 也可以是 mountLocation value
}
});监听事件#
方式一：使用 Webhook#
- 注册 Webhook 端点：
const enabledEvents = [
'customer.subscription.started',
'customer.subscription.renewed'，
'manual.notification',
];
const webhook = await payment.webhookEndpoints.create({
url: 'https://your-app.com/api/payment/callback',
enabled_events: enabledEvents
});- 实现 Webhook 处理：
// api/routes/payment/callback.js
module.exports = {
post: async (req) => {
const event = req.body;
if (event.type === 'manual.notification') {
// 处理邮件信息
await sendCustomEmail(event.data);
}
return { code: 'OK' };
}
};方式二：使用 EventBus#
使用 @blocklet/sdk 的 EventBus 在应用内监听事件：
const EventBus = require('@blocklet/sdk/service/eventbus');
EventBus.subscribe((event) => {
if (event.type === 'manual.notification') {
// 处理邮件信息
sendCustomEmail(event.data.object);
}
});通知数据结构#
{
type: 'customer.subscription.started', // 原有触发的事件类型
data: {
entity: any, // 通知相关的实体数据（订阅、账单信息等）
userDid: string, // 用户 DID
context: { // Payment Kit 对于通知处理完的上下文信息
[key: string]: any // 上下文数据
}
}
}最佳实践#
- 选择合适的配置级别
- 订阅级别：适用于需要对不同订阅采用不同通知策略的场景
- 全局级别：适用于所有订阅使用统一通知策略的场景
- 监听方式选择
- Webhook：适合分布式系统，可跨服务通信
- EventBus：适合单应用内的事件处理，实现更简单