能力介绍

@blocklet/payment-js SDK 为开发者提供了一套强大的工具，可用于通过 Payment Kit API 以编程方式管理支付相关的资源。该 SDK 简化了与订阅、产品、支付等相关的交互，并支持从客户管理到 Webhook 集成等功能。
下文将介绍其核心功能、支持的方法及实际示例。
客户管理#高效管理客户数据，包括检索、更新、搜索、删除客户记录，以及获取当前用户的个人信息。
支持的方法
payment.customers.retrieve(id)	
payment.customers.update(id, data)
payment.customers.list(params)
payment.customers.search(params)
payment.customers.del(id)
payment.customers.me()
示例
const customer = await payment.customers.retrieve('cus_xxx');
console.log(customer);订阅管理#全面管理订阅的完整生命周期，包括创建、更新和用量跟踪（用于计量计费）。
支持的方法
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)
示例
const subscription = await payment.subscriptions.retrieve('sub_xxx');
console.log(subscription);产品与价格管理#创建和管理产品及其定价结构，支持周期计费付款、多币种选项和库存监管。
支持的方法
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 })
示例
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.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)
示例
const refund = await payment.paymentIntents.refund('pi_xxx', {
  amount: '0.001',
  reason: 'requested_by_admin',
});
console.log(refund);结账会话#为支付或订阅提供灵活的结账体验，支持多种配置。
支持的方法
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)
例子
// 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.paymentLinks.create(data)
payment.paymentLinks.retrieve(id)
payment.paymentLinks.update(id, data)
payment.paymentLinks.list(params)
payment.paymentLinks.archive(id)
示例
const link = await payment.paymentLinks.create({
  line_items: [{ price_id: 'price_xxx', quantity: 2 }],
});
console.log(link);使用情况追踪与计量#在订阅期内跟踪和管理按使用量计费的情况。
支持的方法
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)
示例
await payment.subscriptionItems.createUsageRecord({
  subscription_item_id: 'si_xxx',
  quantity: 1,
});Webhook 集成#通过 webhook 终端启用实时事件通知。
支持的方法
payment.webhookEndpoints.create(data)
payment.webhookEndpoints.retrieve(id)
payment.webhookEndpoints.update(id, data)
payment.webhookEndpoints.list(params)
payment.webhookEndpoints.del(id)
示例
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();其他功能#借助这些补充功能提升您的开发体验。
环境灵活：可使用以下方式在测试模式和实时模式之间切换：
payment.environments.setTestMode(boolean)
环境变量：PAYMENT_LIVE_MODE， PAYMENT_TEST_MODE
TypeScript 支持：提供完善的类型定义，实现无缝集成。
错误处理：使用 try-catch 代码块妥善处理错误，并通过 error.message 获取错误详情。
欢迎使用 Payment Kit

User Guides

Developer Guides

能力介绍

客户管理#

订阅管理#

产品与价格管理#

支付处理#

结账会话#

支付链接#

使用情况追踪与计量#

Webhook 集成#

其他功能#

@blocklet/payment-js

快速上手
