結帳會話 | ArcBlock

結帳會話代表顧客付款時的會話。它是收集付款詳細資訊以建立一次性付款或訂閱的主要機制。建立會話後，您會將顧客重新導向到一個安全的、託管的付款頁面。付款完成後，顧客會被重新導向回您的應用程式。

結帳會話物件

結帳會話物件包含有關付款流程的所有詳細資訊，包括訂單項目、付款狀態和顧客資訊。

Attribute	Type	Description
`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', // 或 'subscription'
});

參數

Name	Type	Description
`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` 模式，它將包含價格上定義的任何試用期。

訂單項目屬性

Name	Type	Description
`price_id`	string	Price 物件的 ID。
`quantity`	number	正在購買的訂單項目的數量。預設為 1。
`adjustable_quantity`	object	允許顧客在結帳頁面上調整此訂單項目的數量。包含 `enabled` (布林值)、`minimum` (數字) 和 `maximum` (數字) 屬性。

訂閱資料屬性

Name	Type	Description
`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');

參數

Name	Type	Description
`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'
  }
});

參數

Name	Type	Description
`id`	string	必要。要更新的會話 ID。
`metadata`	object	一組儲存在物件上的鍵值對。這是唯一可以更新的欄位。

更新後的結帳會話物件。

列出所有結帳會話

返回您的結帳會話列表。會話按建立日期排序返回，最新的會話會先出現。

列出結帳會話

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

參數

Name	Type	Description
`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');

參數

Name	Type	Description
`id`	string	必要。要使其過期的結帳會話 ID。

狀態為 expired 的已過期結帳會話物件。

Response

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