Checkout 会话
Checkout 会话创建一个由 PaymentKit 托管的安全页面，用于收集支付信息。它是处理一次性付款（payment 模式）和设置周期性计费（subscription 模式）的基础组件。会话负责协调整个结账流程，从显示订单项到处理支付确认和重定向。
创建会话前，通常需要先配置好你的产品。更多信息，请参阅产品与价格指南。要了解如何在成功结账后管理生成的订阅，请参阅订阅指南。
结账流程#
此流程涉及你的应用程序前端和后端与 PaymentKit API 的交互。用户将被重定向至 PaymentKit 托管的页面以完成支付，这确保了敏感的支付信息绝不会由你的服务器直接处理。
创建 Checkout 会话#
创建一个新的 Checkout 会话。创建成功后，你可以将用户重定向至响应对象中返回的 url。
参数
名称 | 类型 | 描述 |
|---|---|---|
|
| 必填。 客户成功付款后将被重定向到的 URL。 |
|
| 必填。 客户取消付款后将被重定向到的 URL。 |
|
| 必填。 对象数组，每个对象代表一个待购商品。见下方的 |
|
| 必填。 会话模式。必须是 |
|
| 与此会话关联的现有客户的 ID。 |
|
| 当 |
|
| 会话过期的 Unix 时间戳（秒）。会话必须在此时间之前完成。 |
|
| 一组可以附加到此对象的键值对。可用于存储附加信息。 |
|
| 在结账页面上启用优惠码。 |
line_items 结构
名称 | 类型 | 描述 |
|---|---|---|
|
| 必填。 Price 对象的 ID。 |
|
| 必填。 要购买的价格对应的数量。 |
subscription_data 结构
名称 | 类型 | 描述 |
|---|---|---|
|
| 试用期持续天数。 |
|
| 在订阅管理页面上向用户显示的自定义操作数组。 |
请求示例
import payment from '@blocklet/payment-js';
async function createSession() {
try {
const session = await payment.checkout.sessions.create({
success_url: 'https://example.com/success',
cancel_url: 'https://example.com/cancel',
mode: 'subscription',
line_items: [
{ price_id: 'price_xxx', quantity: 1 }
],
subscription_data: {
service_actions: [
{
type: 'notification',
text: { en: 'View Documentation', zh: '查看文档' },
link: 'https://docs.example.com',
triggerEvents: ['customer.subscription.started']
}
]
},
expires_at: Math.floor(Date.now() / 1000) + (60 * 30) // 30 分钟后过期
});
console.log('Checkout 会话 URL:', session.url);
// 将你的客户重定向到 session.url
} catch (error) {
console.error('创建 checkout 会话时出错:', error.message);
}
}
createSession();响应示例
{
"id": "cs_xxx",
"object": "checkout.session",
"livemode": false,
"url": "https://pay.arcblock.io/checkout/cs_xxx",
"status": "open",
"mode": "subscription",
"success_url": "https://example.com/success",
"cancel_url": "https://example.com/cancel",
"customer_id": null,
"line_items": {
"object": "list",
"data": [
{
"id": "li_xxx",
"price_id": "price_xxx",
"quantity": 1
}
]
},
"expires_at": 1729245600,
"payment_status": "unpaid"
}检索 Checkout 会话#
获取先前已创建的 Checkout 会话的详细信息。
参数
名称 | 类型 | 描述 |
|---|---|---|
|
| 必填。 Checkout 会话的唯一标识符。 |
请求示例
import payment from '@blocklet/payment-js';
async function retrieveSession(sessionId) {
try {
const session = await payment.checkout.sessions.retrieve(sessionId);
console.log('会话状态:', session.status);
console.log('支付状态:', session.payment_status);
} catch (error) {
console.error('检索会话时出错:', error.message);
}
}
retrieveSession('cs_xxx');响应示例
{
"id": "cs_xxx",
"object": "checkout.session",
"status": "complete",
"payment_status": "paid",
"customer_id": "cus_xxx",
"subscription_id": "sub_xxx",
"livemode": false,
"url": null,
"line_items": { ... },
"created_at": "2024-10-18T10:00:00.000Z"
}列出 Checkout 会话#
返回一个分页的 Checkout 会话列表。
参数
名称 | 类型 | 描述 |
|---|---|---|
|
| 仅返回指定客户 ID 的会话。 |
|
| 仅返回具有指定状态的会话。可以是 |
|
| 仅返回指定 Payment Intent 的会话。 |
|
| 仅返回指定 Subscription 的会话。 |
|
| 分页的页码。默认为 1。 |
|
| 每页的项目数。默认为 20。 |
请求示例
import payment from '@blocklet/payment-js';
async function listCompletedSessions(customerId) {
try {
const sessions = await payment.checkout.sessions.list({
customer_id: customerId,
status: 'complete',
pageSize: 5
});
console.log(`为客户找到 ${sessions.count} 个已完成的会话。`);
sessions.list.forEach(session => {
console.log(`- 会话 ID: ${session.id}`);
});
} catch (error) {
console.error('列出会话时出错:', error.message);
}
}
listCompletedSessions('cus_xxx');响应示例
{
"count": 15,
"list": [
{
"id": "cs_yyy",
"object": "checkout.session",
"status": "complete",
"payment_status": "paid",
"customer_id": "cus_xxx"
},
{
"id": "cs_zzz",
"object": "checkout.session",
"status": "complete",
"payment_status": "paid",
"customer_id": "cus_xxx"
}
]
}使 Checkout 会话过期#
如果一个 Checkout 会话仍处于 open 状态，则可以使其过期。一旦过期，它将无法用于支付。
参数
名称 | 类型 | 描述 |
|---|---|---|
|
| 必填。 要使其过期的 Checkout 会话的 ID。 |
请求示例
import payment from '@blocklet/payment-js';
async function expireSession(sessionId) {
try {
const session = await payment.checkout.sessions.expire(sessionId);
console.log(`会话 ${session.id} 已过期。状态: ${session.status}`);
} catch (error) {
console.error('使会话过期时出错:', error.message);
}
}
expireSession('cs_abc');响应示例
{
"id": "cs_abc",
"object": "checkout.session",
"status": "expired",
"payment_status": "unpaid",
"livemode": false
}付款后履行订单#
虽然将用户重定向到 success_url 可以提供即时反馈，但这并非履行订单的安全方式。客户可以将成功 URL 添加到书签，并在不付款的情况下直接访问它。
要可靠且安全地管理支付后逻辑，你应该使用 Webhooks。通过监听 checkout.session.completed 事件，你的服务器可以在支付成功时从 PaymentKit 接收通知，从而安全地提供服务或发货。
有关详细指南，请参阅 Webhooks。
本指南介绍了 Checkout 会话的生命周期。现在你可以为你的客户创建支付页面了。有关所有可用参数和方法的完整列表，请访问 Checkout 会话 API 参考。