Payment Kit Event Listening Mechanism
Payment Kit provides two ways to listen for events, enabling you to respond to system events in a timely manner.
Listening Modes#
Method 1: Using Webhooks#
Suitable for distributed systems and supports cross-service communication.
- Register a webhook endpoint
const ensureWebhooks = async () => {
const enabledEvents = [
'customer.subscription.started',
'customer.subscription.renewed',
];
const result = await payment.webhookEndpoints.list({ page: 1, size: 100 });
if (result.list.length) {
const webhook = await payment.webhookEndpoints.update(result.list[0].id, {
url: getUrl('/api/payment/callback'),
enabled_events: enabledEvents,
});
logger.info('webhooks updated', webhook);
return;
}
const webhook = await payment.webhookEndpoints.create({
url: getUrl('/api/payment/callback'),
enabled_events: enabledEvents,
});
logger.info('webhooks created', webhook);
};- Implement callback processing
// api/routes/payment/callback.js
const { verifySig } = require('@blocklet/sdk/lib/middlewares/component');
router.post('/payment/callback', verifySig, (req, res) => {
const event = req.body;
switch(event.type) {
case 'customer.subscription.started':
await handleSubscriptionStart(event.data);
break;
case 'customer.subscription.renewed':
await handleSubscriptionRenew(event.data);
break;
}
}
Method 2: Using the Event Bus#
Suitable for handling events within a single application, simplifying implementation.
const EventBus = require('@blocklet/sdk/service/eventbus');
EventBus.subscribe((event) => {
switch(event.type) {
case 'customer.subscription.started':
handleSubscriptionStart(event.data);
break;
case 'customer.subscription.renewed':
handleSubscriptionRenew(event.data);
break;
}
});Event Type Descriptions#
Checkout Complete#
checkout.session.completed- Checkout session completedcheckout.session.nft_minted- NFT minting complete
Subscribing to Events#
customer.subscription.created- Customer subscription createdcustomer.subscription.started- Subscription initiatedcustomer.subscription.renewed- Customer subscription renewedcustomer.subscription.upgraded- Customer Subscription Upgradedcustomer.subscription.updated- Customer subscription updatedcustomer.subscription.deleted- Subscription canceledcustomer.subscription.paused- Customer subscription pausedcustomer.subscription.resumed- Subscription resumed
Probationary Period Incident#
customer.subscription.trial_start- Trial Start Datecustomer.subscription.trial_will_end- Your trial will end soon.customer.subscription.trial_end- Trial End
Payment Events#
payment_intent.succeeded- Payment successfulpayment_intent.payment_failed- Payment failedinvoice.paid- Invoice payment completedrefund.succeeded- Refund successful