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.

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 completed
checkout.session.nft_minted - NFT minting complete

Subscribing to Events

customer.subscription.created - Customer subscription created
customer.subscription.started - Subscription initiated
customer.subscription.renewed - Customer subscription renewed
customer.subscription.upgraded - Customer Subscription Upgraded
customer.subscription.updated - Customer subscription updated
customer.subscription.deleted - Subscription canceled
customer.subscription.paused - Customer subscription paused
customer.subscription.resumed - Subscription resumed

Probationary Period Incident

customer.subscription.trial_start - Trial Start Date
customer.subscription.trial_will_end - Your trial will end soon.
customer.subscription.trial_end - Trial End

Payment Events

payment_intent.succeeded - Payment successful
payment_intent.payment_failed - Payment failed
invoice.paid - Invoice payment completed
refund.succeeded - Refund successful