自定义通知处理指南

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

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：适合单应用内的事件处理，实现更简单