Skip to main content

Custom Notification Processing Guide

Payment Kit allows applications to handle notifications directly, offering two configuration options.

Option 1: Subscription-Based Access Control

When creating a checkoutSession, use subscription_data.notification_settings to configure notification handling.

javascript
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,                           // enable custom processing
      include_events: ['customer.subscription.started']
    }
  }
});

Approach 2: Global Management

Create global notification configurations using the settings API.

javascript
// 1. create global setting
const setting = await payment.settings.create({
  type: 'notification',
  mountLocation: 'your.app.id',              // use component_did or custom global constant
  description: 'manual notification',
  componentDid: '', // optional, component did
  settings: {
    self_handle: true,                       //  enable custom processing
    include_events: [
      'customer.subscription.started',
      'customer.subscription.renewed'
    ]
  }
});

// 2. releated settings to checkout session
const checkoutSession = await payment.checkout.sessions.create({
  mode: 'subscription',
  line_items: [{ price_id: 'your_price_id', quantity: 1 }],
  metadata: {
    setting_id: setting.id                // setting id or mountLocation value
  }
});

Listening for Events

Method 1: Using a Webhook

  1. Register a webhook endpoint
javascript
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
});
  1. Implement webhook processing
javascript
// 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' };
  }
};

Using the Event Bus

Use the @blocklet/sdk EventBus to listen for events within the application:

javascript
const EventBus = require('@blocklet/sdk/service/eventbus');

EventBus.subscribe((event) => {
  if (event.type === 'manual.notification') {
    sendCustomEmail(event.data.object);
  }
});

Notification Data Structure

javascript
{
  type: 'customer.subscription.started', // original trigger event type
  data: {
    entity: any,                // Notify related entity data (subscription, billing information, etc.)
    userDid: string,
    context: {                  // Payment Kit Context information for notifications that have been processed
      [key: string]: any
    }
  }
}

Best Practices

  1. Selecting the Appropriate Configuration Level
  • Subscription level: For scenarios where different subscriptions require different notification policies
  • Global level: Applies to all subscriptions that use a unified notification policy.
  1. Listener Mode
  • Webhook: Ideal for distributed systems, facilitating inter-service communication
  • EventBus: Ideal for managing events within a single application, offering a simpler implementation.