一次性付款
PaymentKit 提供了多种灵活的方式来处理商品或服务的一次性收费。本指南将详细介绍 Node.js SDK 中可用的三种主要方法，帮助您根据具体需求选择最佳方案。
每种方法都适用于不同的使用场景，从完全托管的支付页面到深度集成的自定义支付流程。
Checkout 会话
最快捷的入门方式。将用户重定向到由 PaymentKit 托管的安全、预构建的支付页面。
支付链接
创建可共享、可重复使用的支付页面链接。非常适合社交媒体、电子邮件或简单的“购买”按钮。
支付意图
支付的基础对象。可用于构建自定义支付 UI 和管理收费生命周期。
Checkout 会话#
Checkout 会话是接受付款的最简单方式。它会创建一个安全的托管支付页面来处理整个结账流程。您只需创建一个会话，将客户重定向到提供的 URL，PaymentKit 就会处理其余事宜。
此方法非常适合标准电子商务流程、捐赠按钮或任何您希望在不自行构建 UI 的情况下获得快速、安全且功能齐全的结账体验的场景。
工作原理#
- 创建会话：您的服务器使用 SDK 创建一个会话，指定订单项、成功和取消 URL 以及其他详细信息。
- 重定向客户：API 返回一个包含
url的会话对象。您将客户重定向到此 URL。 - 客户付款：客户在托管页面上完成付款。
- 重定向回来：PaymentKit 将客户重定向回您的
success_url或cancel_url。
示例：创建 Checkout 会话#
以下是如何为一次性付款创建会话。
Create Checkout Session
import payment from '@blocklet/payment-js';
async function createCheckoutSession() {
try {
const session = await payment.checkout.sessions.create({
mode: 'payment', // 指定为一次性付款
success_url: 'https://your-site.com/payment-success?session_id={CHECKOUT_SESSION_ID}',
cancel_url: 'https://your-site.com/payment-cancelled',
line_items: [
{
price_id: 'price_xxxxxxxxxxxxxx', // 替换为你的 Price ID
quantity: 1,
},
],
expires_at: Math.floor(Date.now() / 1000) + (30 * 60), // 会话在 30 分钟后过期
});
console.log('Checkout 会话 URL：', session.url);
// 现在，将你的用户重定向到 session.url
} catch (error) {
console.error('创建会话时出错：', error.message);
}
}
createCheckoutSession();创建会话后，应使用 session.url 将客户重定向到支付页面。要获取参数和选项的完整列表，请参阅 Checkout 会话 API 参考。
支付链接#
支付链接提供了一种为特定产品创建可重复使用的结账页面链接的方式。创建后，您可以在电子邮件、社交媒体等多个渠道上分享此链接，或将其嵌入网站上一个简单的“立即购买”按钮中。它们非常适合销售单个商品或服务，而无需集成完整的购物车功能。
工作原理#
- 创建链接：使用 SDK 创建一个支付链接，指定一个或多个订单项。
- 分享 URL：API 返回该链接的永久
url。 - 客户付款：任何访问该 URL 的客户都可以完成付款。
示例：创建支付链接#
Create Payment Link
import payment from '@blocklet/payment-js';
async function createPaymentLink() {
try {
const paymentLink = await payment.paymentLinks.create({
line_items: [
{
price_id: 'price_xxxxxxxxxxxxxx', // 替换为你的 Price ID
quantity: 1,
},
],
metadata: {
campaign: 'summer_sale_2024'
}
});
console.log('可分享的支付链接：', paymentLink.url);
} catch (error) {
console.error('创建支付链接时出错：', error.message);
}
}
createPaymentLink();您还可以更新支付链接，例如，在不再需要时使用 payment.paymentLinks.archive(id) 将其归档。要了解更多详情，请访问 支付链接 API 参考。
支付意图#
支付意图对象是 PaymentKit 中所有交易的核心。它跟踪支付从创建到完成的整个生命周期，并在此过程中处理各种身份验证步骤和状态变更。虽然 Checkout 会话和支付链接会自动为您创建和管理支付意图，但您可以直接与其交互以实现更高级的用例，例如构建自定义支付表单或处理支付后操作。
直接与支付意图交互通常用于管理现有付款，例如处理退款。
示例：退款#
支付成功后（例如，通过 Checkout 会话），您可以检索关联的支付意图 ID，并用它来处理退款。
Refund a Payment
import payment from '@blocklet/payment-js';
// 支付意图 ID 通常从已完成的 Checkout 会话中获取
// 或通过 webhook 事件获取。
const paymentIntentId = 'pi_xxxxxxxxxxxxxx';
async function refundPayment(pi_id) {
try {
const refund = await payment.paymentIntents.refund(pi_id, {
amount: '10.00', // 要退款的金额
reason: 'requested_by_customer',
description: '客户对产品不满意。',
});
console.log('退款处理成功：', refund.id);
} catch (error) {
console.error(`退款 ${pi_id} 时出错：`, error.message);
}
}
refundPayment(paymentIntentId);这使您能够在初始收费完成后对支付生命周期进行精细控制。要获取完整的管理功能列表，请参阅 支付意图 API 参考。
既然您已了解如何创建一次性收费，您可能希望学习如何为周期性计费实现 订阅，或设置 Webhooks 以接收有关支付事件的实时通知。