Capabilities

The @blocklet/payment-js SDK empowers developers with a robust suite of tools to programmatically manage payment-related resources via the PaymentKit API. From customer management to webhook integration, this SDK streamlines interactions with subscriptions, products, payments, and more. Below are its core capabilities, complete with supported methods and practical examples.
Customer Management#Efficiently manage customer data, including retrieval, updates, searches, deletions, and access to the current user’s profile.
Supported Methods
payment.customers.retrieve(id)	
payment.customers.update(id, data)
payment.customers.list(params)
payment.customers.search(params)
payment.customers.del(id)
payment.customers.me()
Example
const customer = await payment.customers.retrieve('cus_xxx');

console.log(customer);Subscription Management#Oversee subscriptions with full lifecycle control, including creation, updates, and usage tracking for metered billing.
Supported Methods
payment.subscriptions.create(data)
payment.subscriptions.retrieve(id)
payment.subscriptions.update(id, data)
payment.subscriptions.list(params)
payment.subscriptions.search(params)
payment.subscriptions.cancel(id, options)
payment.subscriptions.recover(id)
payment.subscriptions.pause(id)
payment.subscriptions.resume(id)
payment.subscriptions.del(id)
Example
const subscription = await payment.subscriptions.retrieve('sub_xxx');

console.log(subscription);Product and Price Management#Create and manage products and their pricing structures, supporting recurring payments, multi-currency options, and inventory oversight.
Supported Methods
payment.products.create(data)	
payment.products.retrieve(id)
payment.products.update(id, data)
payment.products.list(params)
payment.products.search(params)
payment.products.archive(id)
payment.products.del(id)
payment.prices.create(data)
payment.prices.retrieve(id)
payment.prices.update(id, data)
payment.prices.list(params)
payment.prices.search(params)
payment.prices.archive(id)
payment.prices.del(id)
payment.prices.inventory(id, { action, quantity })
Example
const product = await payment.products.create({
  name: 'Test Product',
  type: 'good',
  description: 'Product description',
  prices: [{ type: 'one_time', unit_amount: '0.001' }],
});
console.log('Default product and price created:', product);Payment Processing#Handle payment intents and execute refunds with customizable options.
Supported Methods
payment.paymentIntents.create(data)	
payment.paymentIntents.retrieve(id)
payment.paymentIntents.update(id, data)
payment.paymentIntents.list(params)
payment.paymentIntents.search(params)
payment.paymentIntents.refund(id, data)
payment.refunds.create(data)
payment.refunds.retrieve(id)
payment.refunds.list(params)
payment.refunds.search(params)
Example
const refund = await payment.paymentIntents.refund('pi_xxx', {
  amount: '0.001',
  reason: 'requested_by_admin',
});
console.log(refund);Checkout Sessions#Facilitate checkout experiences for payments or subscriptions with flexible configurations.
Supported Methods
payment.checkout.sessions.create(data)
payment.checkout.sessions.retrieve(id)
payment.checkout.sessions.update(id, data)
payment.checkout.sessions.list(params)
payment.checkout.sessions.expire(id)
Example
// Simple Checkout Creation
const checkoutSession = await payment.checkout.sessions.create({
    line_items: [{ price_id: 'price_xxx', quantity: 2 }],
});

// With Callbacks
const checkoutSession = await payment.checkout.sessions.create({
    success_url: 'success callback link',
    cancel_url: 'cancel callback link',
    line_items: [{ price_id: 'price_xxx', quantity: 2 }],
});

// Custom Notification Button
const checkoutSession = await payment.checkout.sessions.create({
    mode: 'payment',
    line_items: [{ price_id: 'price_xxx', quantity: 2 }],
    subscription_data: {
      service_actions: [
        {
          type: 'notification',
          text: { zh: '查看文档', en: 'View Documentation' },
          link: 'https://www.arcblock.io/docs/createblocklet/en/quick-start',
          triggerEvents: ['customer.subscription.started'],
        },
      ],
    },
  });

console.log(checkoutSession.url);Payment Links#Generate and manage reusable payment links for streamlined transactions.
Supported Methods
payment.paymentLinks.create(data)
payment.paymentLinks.retrieve(id)
payment.paymentLinks.update(id, data)
payment.paymentLinks.list(params)
payment.paymentLinks.archive(id)
Example
const link = await payment.paymentLinks.create({
  line_items: [{ price_id: 'price_xxx', quantity: 2 }],
});
console.log(link);Usage Tracking and Metering#Track and manage usage for metered billing within subscriptions.
Supported Methods
payment.subscriptionItems.create(data)
payment.subscriptionItems.retrieve(id)
payment.subscriptionItems.update(id, data)
payment.subscriptionItems.list(params)
payment.subscriptionItems.del(id)
payment.subscriptionItems.createUsageRecord(data)
payment.subscriptionItems.listUsageRecordSummaries(id)
payment.subscriptionItems.listUsageRecords(params)
Example
await payment.subscriptionItems.createUsageRecord({
  subscription_item_id: 'si_xxx',
  quantity: 1,
});Webhook Integration#Enable real-time event notifications through webhook endpoints.
Supported Methods
payment.webhookEndpoints.create(data)
payment.webhookEndpoints.retrieve(id)
payment.webhookEndpoints.update(id, data)
payment.webhookEndpoints.list(params)
payment.webhookEndpoints.del(id)
Example
const { getUrl } = require('@blocklet/sdk/lib/component');

const ensureWebhooks = async () => {
  const enabledEvents = [
    'checkout.session.completed',
    'checkout.session.nft_minted',
    'customer.subscription.created',
    'customer.subscription.deleted',
    'customer.subscription.paused',
    'customer.subscription.updated',
    'customer.subscription.started',
    'customer.subscription.renewed',
    'payment_intent.created',
    'payment_intent.succeeded',
  ];

  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,
    });
    console.log('Webhooks updated:', webhook);
    return;
  }

  const webhook = await payment.webhookEndpoints.create({
    url: getUrl('/api/payment/callback'),
    enabled_events: enabledEvents,
  });
  console.log('Webhooks created:', webhook);
};

ensureWebhooks();Additional Features#Enhance your development experience with these supplementary capabilities.
 Environment Flexibility:  Toggle between test and live modes using:  
payment.environments.setTestMode(boolean)
Environment variables: PAYMENT_LIVE_MODE, PAYMENT_TEST_MODE
TypeScript Support: Full type definitions for seamless integration.
Error Handling:  Capture and manage errors gracefully with try-catch blocks, accessing details via error.message.
Welcome to use Payment Kit.

User Guides

Developer Guides

Capabilities

Customer Management#

Subscription Management#

Product and Price Management#

Payment Processing#

Checkout Sessions#

Payment Links#

Usage Tracking and Metering#

Webhook Integration#

Additional Features#

@blocklet/payment-js

Quick Start
