结账会话

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

相关指南：一次性付款，订阅。

结账会话对象#

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

属性

类型

描述

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",
  // ... 其他属性
}
API 参考
优惠券