API 参考

结账会话

结账会话用于协调一次性付款或订阅的支付流程。当顾客准备付款时，你创建一个会话，并将其重定向到该会话的唯一 URL。本指南涵盖了用于管理结账会话的 API。
有关实际示例和实现演练，请参阅我们的结账会话使用指南。
结账会话对象#结账会话对象包含有关单个购买流程的所有详细信息。
属性
类型
描述
id
string
结账会话的唯一标识符。
url
string
应将顾客重定向至此 URL 以完成支付。此 URL 仅在创建后可用。
status
string
会话的当前状态。可以是 'open'、'complete' 或 'expired'。
payment_status
string
会话的支付状态。可以是 'paid'、'unpaid' 或 'no_payment_required'。
mode
string
结账会话的模式，决定其用途。可以是 'payment'、'setup' 或 'subscription'。
customer_id
string
关联 Customer 的 ID（如果存在）。
subscription_id
string
如果会话处于 subscription 模式，则为所创建 Subscription 的 ID。
line_items
Array<Object>
顾客正在购买的商品列表。
success_url
string
成功支付后重定向到的 URL。
cancel_url
string
如果顾客取消支付流程，重定向到的 URL。
expires_at
number
会话将过期的 Unix 时间戳。
metadata
Object
可附加到对象上供自己参考的一组键值对。
创建结账会话#创建一个新会话以启动支付或订阅流程。
参数
名称
类型
描述
mode
string
结账会话的模式。必需。可以是 'payment'、'setup' 或 'subscription'。
line_items
Array<Object>
会话的订单项列表。每个项目对象必须包含 price_id 和 quantity。必需。
success_url
string
顾客成功购买后将被引导至的 URL。必需。
cancel_url
string
如果顾客取消购买，将被引导至的 URL。必需。
customer_id
string
要与此会话关联的现有 Customer 的 ID。可选。
payment_method_types
Array<string>
要接受的支付方式类型列表（例如 'stripe'、'arcblock'）。可选。
allow_promotion_codes
boolean
启用用户可兑换的优惠码。可选。
subscription_data
Object
当 mode 为 'subscription' 时使用的数据，例如 trial_period_days。可选。
metadata
Object
与会话一同存储的键值数据。可选。
返回
返回新创建的 TCheckoutSession 对象。url 属性包含供顾客重定向的链接。
示例
async function createCheckoutSession() {
  try {
    const session = await payment.checkoutSessions.create({
      success_url: 'https://example.com/success?session_id={CHECKOUT_SESSION_ID}',
      cancel_url: 'https://example.com/cancel',
      line_items: [{
        price_id: 'price_123456789',
        quantity: 2,
      }],
      mode: 'payment',
      metadata: {
        order_id: 'order_abc123'
      }
    });
    console.log('Redirect your customer to:', session.url);
  } catch (error) {
    console.error('Error creating session:', error);
  }
}

createCheckoutSession();响应示例
{
  "id": "cs_xxxxxxxxxxxxxx",
  "object": "checkout.session",
  "url": "https://pay.arcblock.io/session/cs_xxxxxxxxxxxxxx",
  "status": "open",
  "payment_status": "unpaid",
  "mode": "payment",
  "success_url": "https://example.com/success?session_id={CHECKOUT_SESSION_ID}",
  "cancel_url": "https://example.com/cancel",
  "customer_id": null,
  "line_items": [
    {
      "price_id": "price_123456789",
      "quantity": 2
    }
  ],
  "expires_at": 1678886400,
  "metadata": {
    "order_id": "order_abc123"
  }
}检索结账会话#通过 ID 获取现有结账会话的详细信息。这对于在顾客被重定向后检查状态非常有用。
参数
名称
类型
描述
id
string
结账会话的唯一标识符。必需。
返回
返回 TCheckoutSessionExpanded 对象，该对象比标准会话对象包含更多详细信息。
示例
async function retrieveCheckoutSession(sessionId) {
  try {
    const session = await payment.checkoutSessions.retrieve(sessionId);
    console.log('Session status:', session.status);
    console.log('Payment status:', session.payment_status);
  } catch (error) {
    console.error('Error retrieving session:', error);
  }
}

retrieveCheckoutSession('cs_xxxxxxxxxxxxxx');响应示例
{
  "id": "cs_xxxxxxxxxxxxxx",
  "object": "checkout.session",
  "status": "complete",
  "payment_status": "paid",
  "mode": "payment",
  "customer_id": "cus_yyyyyyyyyyyyyy",
  "payment_intent_id": "pi_zzzzzzzzzzzzzzz",
  "metadata": {
    "order_id": "order_abc123"
  }
}更新结账会话#更新现有的结账会话。目前，只能修改 metadata。
参数
名称
类型
描述
id
string
要更新的结账会话的 ID。必需。
metadata
Object
要与会话一同存储的一组键值对。任何现有的元数据都将被替换。必需。
返回
返回更新后的 TCheckoutSession 对象。
示例
async function updateCheckoutSession(sessionId) {
  try {
    const session = await payment.checkoutSessions.update(sessionId, {
      metadata: { 
        order_id: 'order_abc123',
        shipped: 'false'
      }
    });
    console.log('Updated metadata:', session.metadata);
  } catch (error) {
    console.error('Error updating session:', error);
  }
}

updateCheckoutSession('cs_xxxxxxxxxxxxxx');响应示例
{
  "id": "cs_xxxxxxxxxxxxxx",
  "object": "checkout.session",
  "status": "open",
  "metadata": {
    "order_id": "order_abc123",
    "shipped": "false"
  }
}列出所有结账会话#返回所有结账会话的分页列表。你可以根据各种条件筛选列表。
参数
名称
类型
描述
status
string
按会话状态（'open'、'complete' 或 'expired'）筛选。可选。
payment_status
string
按支付状态（'paid'、'unpaid' 或 'no_payment_required'）筛选。可选。
customer_id
string
仅返回指定 Customer ID 的会话。可选。
payment_intent_id
string
仅返回指定 Payment Intent 的会话。可选。
subscription_id
string
仅返回指定 Subscription 的会话。可选。
page
number
分页的页码。可选。
pageSize
number
每页的项目数。默认为 20。可选。
返回
一个分页对象，其中包含 TCheckoutSessionExpanded 对象列表和匹配记录的总数 count。
示例
async function listCompletedSessions() {
  try {
    const sessions = await payment.checkoutSessions.list({
      status: 'complete',
      limit: 10
    });
    console.log(`Found ${sessions.count} completed sessions.`);
    sessions.list.forEach(session => {
      console.log(`- ${session.id}`);
    });
  } catch (error) {
    console.error('Error listing sessions:', error);
  }
}

listCompletedSessions();响应示例
{
  "count": 5,
  "list": [
    {
      "id": "cs_session_abc",
      "status": "complete",
      "payment_status": "paid"
    },
    {
      "id": "cs_session_def",
      "status": "complete",
      "payment_status": "paid"
    }
  ]
}使结账会话过期#手动使一个开放的结账会话过期。一旦过期，顾客将无法完成支付。
参数
名称
类型
描述
id
string
要使其过期的结账会话的 ID。必需。
返回
返回状态设置为 expired 的 TCheckoutSession 对象。
示例
async function expireCheckoutSession(sessionId) {
  try {
    const session = await payment.checkoutSessions.expire(sessionId);
    console.log(`Session ${session.id} status is now: ${session.status}`);
  } catch (error) {
    console.error('Error expiring session:', error);
  }
}

expireCheckoutSession('cs_xxxxxxxxxxxxxx');响应示例
{
  "id": "cs_xxxxxxxxxxxxxx",
  "object": "checkout.session",
  "status": "expired",
  "payment_status": "unpaid",
  "mode": "payment"
}
管理结账会话后，你可能希望了解更多关于处理 Subscriptions 或管理 Payment Intents 的信息。

属性	类型	描述
`id`	`string`	结账会话的唯一标识符。
`url`	`string`	应将顾客重定向至此 URL 以完成支付。此 URL 仅在创建后可用。
`status`	`string`	会话的当前状态。可以是 `'open'`、`'complete'` 或 `'expired'`。
`payment_status`	`string`	会话的支付状态。可以是 `'paid'`、`'unpaid'` 或 `'no_payment_required'`。
`mode`	`string`	结账会话的模式，决定其用途。可以是 `'payment'`、`'setup'` 或 `'subscription'`。
`customer_id`	`string`	关联 Customer 的 ID（如果存在）。
`subscription_id`	`string`	如果会话处于 `subscription` 模式，则为所创建 Subscription 的 ID。
`line_items`	`Array<Object>`	顾客正在购买的商品列表。
`success_url`	`string`	成功支付后重定向到的 URL。
`cancel_url`	`string`	如果顾客取消支付流程，重定向到的 URL。
`expires_at`	`number`	会话将过期的 Unix 时间戳。
`metadata`	`Object`	可附加到对象上供自己参考的一组键值对。

名称	类型	描述
`mode`	`string`	结账会话的模式。必需。可以是 `'payment'`、`'setup'` 或 `'subscription'`。
`line_items`	`Array<Object>`	会话的订单项列表。每个项目对象必须包含 `price_id` 和 `quantity`。必需。
`success_url`	`string`	顾客成功购买后将被引导至的 URL。必需。
`cancel_url`	`string`	如果顾客取消购买，将被引导至的 URL。必需。
`customer_id`	`string`	要与此会话关联的现有 Customer 的 ID。可选。
`payment_method_types`	`Array<string>`	要接受的支付方式类型列表（例如 `'stripe'`、`'arcblock'`）。可选。
`allow_promotion_codes`	`boolean`	启用用户可兑换的优惠码。可选。
`subscription_data`	`Object`	当 `mode` 为 `'subscription'` 时使用的数据，例如 `trial_period_days`。可选。
`metadata`	`Object`	与会话一同存储的键值数据。可选。

名称	类型	描述
`status`	`string`	按会话状态（`'open'`、`'complete'` 或 `'expired'`）筛选。可选。
`payment_status`	`string`	按支付状态（`'paid'`、`'unpaid'` 或 `'no_payment_required'`）筛选。可选。
`customer_id`	`string`	仅返回指定 Customer ID 的会话。可选。
`payment_intent_id`	`string`	仅返回指定 Payment Intent 的会话。可选。
`subscription_id`	`string`	仅返回指定 Subscription 的会话。可选。
`page`	`number`	分页的页码。可选。
`pageSize`	`number`	每页的项目数。默认为 20。可选。

概述

快速入门

核心概念

使用指南

API 参考

TypeScript 支持

结账会话

结账会话对象#

创建结账会话#

检索结账会话#

更新结账会话#

列出所有结账会话#

使结账会话过期#

支付链接

订阅

名称	类型	描述
`id`	`string`	要更新的结账会话的 ID。必需。
`metadata`	`Object`	要与会话一同存储的一组键值对。任何现有的元数据都将被替换。必需。