チェックアウトセッション

チェックアウトセッションは、顧客が支払いを行う際のセッションを表します。これは、一回限りの支払いやサブスクリプションを作成するための支払い情報を収集する主要な仕組みです。セッションを作成すると、顧客は安全なホスト型支払いページにリダイレクトされます。支払いが完了すると、顧客はあなたのアプリケーションにリダイレクトされて戻ります。

関連ガイド: 一回限りの支払い、サブスクリプション。

チェックアウトセッションオブジェクト

チェックアウトセッションオブジェクトには、ラインアイテム、支払いステータス、顧客情報など、支払いフローに関するすべての詳細が含まれています。

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 タイムスタンプ。

チェックアウトセッションの作成

顧客が支払い情報を入力するためのセッションを作成します。

Create a Checkout Session

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'
});

パラメータ

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	価格オブジェクトの ID。
`quantity`	number	購入されるラインアイテムの数量。デフォルトは 1 です。
`adjustable_quantity`	object	チェックアウトページで顧客がこのラインアイテムの数量を調整できるようにします。`enabled` (boolean)、`minimum` (number)、`maximum` (number) のプロパティが含まれます。

サブスクリプションデータプロパティ

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,
  // ... other properties
}

チェックアウトセッションの取得

既存のチェックアウトセッションの詳細を取得します。

Retrieve a Checkout Session

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",
  // ... other properties
}

チェックアウトセッションの更新

渡されたパラメータの値を設定して、チェックアウトセッションオブジェクトを更新します。指定されなかったパラメータは変更されません。

Update a Checkout Session

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

パラメータ

Name	Type	Description
`id`	string	必須。更新するセッションの ID。
`metadata`	object	オブジェクトに保存するキーと値のペアのセット。これが更新できる唯一のフィールドです。

戻り値

更新されたチェックアウトセッションオブジェクト。

すべてのチェックアウトセッションを一覧表示

チェックアウトセッションのリストを返します。セッションは作成日順にソートされ、最新のセッションが最初に表示されます。

List Checkout Sessions

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",
      // ... other properties
    },
    {
      "id": "cs_987654321",
      "object": "checkout.session",
      "status": "open",
      // ... other properties
    }
  ]
}

チェックアウトセッションを期限切れにする

チェックアウトセッションを手動で期限切れにします。この操作は元に戻せません。

Expire a Checkout Session

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

パラメータ

Name	Type	Description
`id`	string	必須。期限切れにするチェックアウトセッションの ID。

戻り値

ステータスが expired の期限切れになったチェックアウトセッションオブジェクト。

Response

{
  "id": "cs_123456789",
  "object": "checkout.session",
  "status": "expired",
  // ... other properties
}