结账会话 | ArcBlock

结账会话代表客户进行付款时的会话。它是收集付款详细信息以创建一次性付款或订阅的主要机制。创建会话后，您需要将客户重定向到一个安全的、托管的支付页面。付款完成后，客户将被重定向回您的应用程序。

结账会话对象

结账会话对象包含有关支付流程的所有详细信息，包括订单项、支付状态和客户信息。

属性	类型	描述
`id`	string	对象的唯一标识符。
`url`	string	您应将客户重定向到此 URL 以完成支付。
`status`	string	结账会话的状态。可以是 `open`、`complete` 或 `expired`。
`payment_status`	string	会话的支付状态。可以是 `paid`、`unpaid` 或 `no_payment_required`。
`mode`	string	结账会话的模式，决定了所收集的付款类型。可以是 `payment`、`setup` 或 `subscription`。
`amount_subtotal`	string	所有订单项价格的总和。
`amount_total`	string	应用折扣和税费后的总金额。
`currency_id`	string	用于支付的货币 ID。
`customer_id`	string	此会话的客户 ID。
`line_items`	array	客户正在购买的商品列表。
`metadata`	object	您可以附加到对象上的一组键值对。
`success_url`	string	成功付款后重定向到的 URL。
`cancel_url`	string	如果客户取消会话，重定向到的 URL。
`expires_at`	number	结账会话将过期的 Unix 时间戳。

创建结账会话

为客户创建一个会话以输入其付款详细信息。

创建一个结账会话

const session = await payment.checkoutSessions.create({
  success_url: 'https://example.com/success',
  cancel_url: 'https://example.com/cancel',
  line_items: [
    {
      price_id: 'price_12345',
      quantity: 1,
    },
  ],
  mode: 'payment', // or 'subscription'
});

参数

名称	类型	描述
`line_items`	array	必需。订单项对象列表。有关详细信息，请参阅下方的订单项属性表。
`success_url`	string	必需。客户成功付款后将被引导至的 URL。
`cancel_url`	string	必需。如果客户取消付款，将被引导至的 URL。
`allow_promotion_codes`	boolean	启用促销代码。默认为 `false`。
`billing_address_collection`	string	指定是否收集客户的账单地址。可以是 `auto` 或 `required`。默认为 `auto`。
`client_reference_id`	string	用于引用结账会话的唯一字符串。这可用于将会话与您的内部系统进行对账。
`customer_id`	string	要与此会话关联的现有客户的 ID。
`customer_creation`	string	确定如何处理客户创建。可以是 `if_required` 或 `always`。默认为 `always`。
`expires_at`	number	会话将在此 Unix 时间戳后过期。默认为自创建起 24 小时。
`metadata`	object	一组用于存储有关对象的附加信息的键值对。
`payment_intent_data`	object	将用于创建底层 PaymentIntent 的数据。请参阅下方的 Payment Intent 数据属性表。
`subscription_data`	object	如果会话处于 `subscription` 模式，将用于创建订阅的数据。请参阅下方的订阅数据属性表。
`include_free_trial`	boolean	如果为 `true` 且会话处于 `subscription` 模式，它将包含价格上定义的任何试用期。

订单项属性

名称	类型	描述
`price_id`	string	Price 对象的 ID。
`quantity`	number	正在购买的订单项数量。默认为 1。
`adjustable_quantity`	object	允许客户在结账页面上调整此订单项的数量。包含 `enabled` (布尔值)、`minimum` (数字) 和 `maximum` (数字) 属性。

订阅数据属性

名称	类型	描述
`description`	string	订阅的可选描述。
`trial_period_days`	number	订阅的试用天数。
`metadata`	object	一组存储在订阅上的键值对。

已创建的结账会话对象。

Response

{
  "id": "cs_123456789",
  "object": "checkout.session",
  "url": "https://checkout.example.com/pay/cs_123456789",
  "status": "open",
  "payment_status": "unpaid",
  "mode": "payment",
  "success_url": "https://example.com/success",
  "cancel_url": "https://example.com/cancel",
  "line_items": [
    {
      "price_id": "price_12345",
      "quantity": 1
    }
  ],
  "expires_at": 1678886400,
  // ... 其他属性
}

检索结账会话

检索现有结账会话的详细信息。

检索一个结账会话

const session = await payment.checkoutSessions.retrieve('cs_123456789');

参数

名称	类型	描述
`id`	string	必需。要检索的结账会话的唯一标识符。

检索到的结账会话对象。

Response

{
  "id": "cs_123456789",
  "object": "checkout.session",
  "status": "complete",
  "payment_status": "paid",
  // ... 其他属性
}

更新结账会话

通过设置传入参数的值来更新结账会话对象。任何未提供的参数将保持不变。

更新一个结账会话

const session = await payment.checkoutSessions.update('cs_123456789', {
  metadata: {
    order_id: '6735'
  }
});

参数

名称	类型	描述
`id`	string	必需。要更新的会话 ID。
`metadata`	object	一组存储在对象上的键值对。这是唯一可以更新的字段。

更新后的结账会话对象。

列出所有结账会话

返回您的结账会话列表。会话按创建日期排序返回，最新的会话最先出现。

列出结账会话

const sessions = await payment.checkoutSessions.list({
  limit: 5,
  status: 'open'
});

参数

名称	类型	描述
`status`	string	按状态筛选会话。可以是 `open`、`complete` 或 `expired`。
`payment_status`	string	按支付状态筛选会话。可以是 `paid`、`unpaid` 或 `no_payment_required`。
`customer_id`	string	仅返回给定客户 ID 的会话。
`customer_did`	string	仅返回给定客户 DID 的会话。
`payment_intent_id`	string	仅返回给定 PaymentIntent 的会话。
`payment_link_id`	string	仅返回从给定支付链接创建的会话。
`subscription_id`	string	仅返回给定订阅的会话。
`metadata.{key}`	string	按自定义元数据字段筛选。例如 `metadata.order_id: '6735'`。
`page`	number	用于分页的页码。默认为 `1`。
`pageSize`	number	每页的项目数。默认为 `20`。

一个包含结账会话对象 list 的分页对象。

Response

{
  "count": 15,
  "list": [
    {
      "id": "cs_123456789",
      "object": "checkout.session",
      "status": "open",
      // ... 其他属性
    },
    {
      "id": "cs_987654321",
      "object": "checkout.session",
      "status": "open",
      // ... 其他属性
    }
  ]
}

使结账会话过期

手动使结账会话过期。此操作不可逆。

使一个结账会话过期

const session = await payment.checkoutSessions.expire('cs_123456789');

参数

名称	类型	描述
`id`	string	必需。要使其过期的结账会话 ID。

状态为 expired 的已过期结账会话对象。

Response

{
  "id": "cs_123456789",
  "object": "checkout.session",
  "status": "expired",
  // ... 其他属性
}