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.
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.
// 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#
- Register a webhook endpoint
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
});- Implement webhook processing
// 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:
const EventBus = require('@blocklet/sdk/service/eventbus');
EventBus.subscribe((event) => {
if (event.type === 'manual.notification') {
sendCustomEmail(event.data.object);
}
});Notification Data Structure#
{
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#
- 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.
- Listener Mode
- Webhook: Ideal for distributed systems, facilitating inter-service communication
- EventBus: Ideal for managing events within a single application, offering a simpler implementation.