# エージェント型コマースプロトコル決済エンドポイントを構築する

エージェント型コマースプロトコル仕様についてご覧ください。

ACP (エージェント型コマースプロトコル) により、AI エージェントは買い手と売り手の間のコマース取引を管理できます。この仕様では、Checkout フローを作成、更新、完了するための方法とデータ構造を定義します。

REST 導入の例は以下のとおりです。

> #### エージェンティックコマースプロトコルの用語
> 
> ACP の定義に使用される用語のなかには、Stripe API で使われる用語と類似しているものがあります。それらを慎重に区別してください。例えばこの文脈では、“agentic checkout session (エージェントによる決済セッション)” は買い手と AI エージェントとのコミュニケーションを指します。これは Stripe Checkout Sessions API とは何の関係もありません。

## エージェンティック決済セッションの作成

買い手の詳細、項目、配送先情報を含む新しいエージェンティック決済セッションを作成できます。

### リクエスト

リクエストに必要なパラメーターを指定します。

| パラメーター                   | タイプ                                                                                                           | 説明              |
| ------------------------ | ------------------------------------------------------------------------------------------------------------- | --------------- |
| **items**                | `array` [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#item)              | 購入できる項目の配列。(必須) |
| **買い手**                  | `hash` (optional) [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#buyer)   | 買い手に関する情報。      |
| **fulfillment\_address** | `hash` (optional) [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#address) | 注文の配送先住所。       |

**リクエスト例:**

```json
POST /checkouts
{
  "items": [
    {
      "id": "item_123",
      "quantity": 2
    }
  ],
  "buyer": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com",
    "phone_number": "+1234567890"
  },
  "fulfillment_address": {
    "name": "John Doe",
    "line_one": "123 Main St",
    "line_two": "Apt 4B",
    "city": "San Francisco",
    "state": "CA",
    "country": "US",
    "postal_code": "94105"
  }
}
```

### レスポンス

レスポンスは売り手から Checkout の現在の状態を返します。

| パラメーター                      | タイプ                                                                                                                 | 説明                                                                                                                              |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| **id**                      | `string`                                                                                                            | エージェンティック決済セッションの一意の識別子。(必須)                                                                                                    |
| **買い手**                     | `hash` (optional) [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#buyer)         | 買い手に関する情報。                                                                                                                      |
| **payment\_provider**       | `hash` (オプション) [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#payment-provider) | 決済代行業者の設定とサポートされている決済手段。                                                                                                        |
| **status**                  | `string`                                                                                                            | Checkout プロセスの現在のステータス。(必須)

  使用可能な値: `not_ready_for_payment` | `ready_for_payment` | `completed` | `canceled` | `in_progress` |
| **currency**                | `string`                                                                                                            | 小文字の 3 文字の ISO 通貨コード。(必須)                                                                                                       |
| **line\_items**             | `array` [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#line-item)               | Checkout プロセスの項目の配列。(必須)                                                                                                        |
| **fulfillment\_address**    | `hash` (optional) [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#address)       | 注文の配送先住所。                                                                                                                       |
| **fulfillment\_options**    | `array` [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#fulfillment-option)      | 利用可能な配送オプションとフルフィルメントオプション。(必須)                                                                                                 |
| **fulfillment\_option\_id** | `string` (optional)                                                                                                 | 現在選択されているフルフィルメントオプションの ID。                                                                                                     |
| **totals**                  | `array` [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#total)                   | 請求と割引の概要。(必須)                                                                                                                   |
| **messages**                | `array` [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#message)                 | Checkout プロセスに関連するメッセージまたは通知の配列。(必須)                                                                                            |
| **links**                   | `array` [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#link)                    | Checkout プロセスに関連するリンクの配列。(必須)                                                                                                   |

**レスポンス例:**

```json
{
  "id": "checkout_abc123",
  "buyer": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com",
    "phone_number": "+1234567890"
  },
  "payment_provider": {
    "provider": "stripe",
    "supported_payment_methods": ["card"]
  },
  "status": "ready_for_payment",
  "currency": "usd",
  "line_items": [
    {
      "id": "item_123",
      "item": {
        "id": "item_123",
        "quantity": 2
      },
      "base_amount": 2000,
      "discount": 0,
      "total": 2000,
      "subtotal": 2000,
      "tax": 0
    }
  ],
  "fulfillment_address": {
    "name": "John Doe",
    "line_one": "123 Main St",
    "line_two": "Apt 4B",
    "city": "San Francisco",
    "state": "CA",
    "country": "US",
    "postal_code": "94105"
  },
  "fulfillment_options": [
    {
      "type": "shipping",
      "id": "shipping_fast",
      "title": "Express Shipping",
      "subtitle": "2-3 business days",
      "carrier": "Shipping Co",
      "subtotal": 150,
      "tax": 0,
      "total": 150
    }
  ],
  "fulfillment_option_id": "shipping_fast",
  "totals": [
    {
      "type": "subtotal",
      "display_text": "Subtotal",
      "amount": 2000
    },
    {
      "type": "fulfillment",
      "display_text": "Shipping",
      "amount": 150
    },
    {
      "type": "tax",
      "display_text": "Tax",
      "amount": 100
    },
    {
      "type": "total",
      "display_text": "Total",
      "amount": 2250
    }
  ],
  "messages": [],
  "links": []
}
```

## Checkout オブジェクトを取得する

ID を使用して既存のエージェンティック Checkout セッションを取得するには、リクエストに含まれる ID を使用して適切な API エンドポイントにリクエストを行います。

### リクエスト

リクエストに必要なパラメーターを指定します。

| パラメーター | タイプ      | 説明                        |
| ------ | -------- | ------------------------- |
| **id** | `string` | Checkout プロセスの一意の識別子。(必須) |

**リクエスト例:**

```json
GET /checkouts/:id
```

### レスポンス

レスポンスは売り手から Checkout の現在の状態を返します。

| パラメーター                      | タイプ                                                                                                                 | 説明                                                                                                                              |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| **id**                      | `string`                                                                                                            | エージェンティック決済セッションの一意の識別子。(必須)                                                                                                    |
| **買い手**                     | `hash` (optional) [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#buyer)         | 買い手に関する情報。                                                                                                                      |
| **payment\_provider**       | `hash` (オプション) [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#payment-provider) | 決済代行業者の設定とサポートされている決済手段。                                                                                                        |
| **status**                  | `string`                                                                                                            | Checkout プロセスの現在のステータス。(必須)

  使用可能な値: `not_ready_for_payment` | `ready_for_payment` | `completed` | `canceled` | `in_progress` |
| **currency**                | `string`                                                                                                            | 小文字の 3 文字の ISO 通貨コード。(必須)                                                                                                       |
| **line\_items**             | `array` [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#line-item)               | Checkout プロセスの項目の配列。(必須)                                                                                                        |
| **fulfillment\_address**    | `hash` (optional) [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#address)       | 注文の配送先住所。                                                                                                                       |
| **fulfillment\_options**    | `array` [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#fulfillment-option)      | 利用可能な配送オプションとフルフィルメントオプション。(必須)                                                                                                 |
| **fulfillment\_option\_id** | `string` (optional)                                                                                                 | 現在選択されているフルフィルメントオプションの ID。                                                                                                     |
| **totals**                  | `array` [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#total)                   | 請求と割引の概要。(必須)                                                                                                                   |
| **messages**                | `array` [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#message)                 | Checkout プロセスに関連するメッセージまたは通知の配列。(必須)                                                                                            |
| **links**                   | `array` [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#link)                    | Checkout プロセスに関連するリンクの配列。(必須)                                                                                                   |

**レスポンス例:**

```json
{
  "id": "checkout_abc123",
  "buyer": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com",
    "phone_number": "+1234567890"
  },
  "payment_provider": {
    "provider": "stripe",
    "supported_payment_methods": ["card"]
  },
  "status": "ready_for_payment",
  "currency": "usd",
  "line_items": [
    {
      "id": "item_123",
      "item": {
        "id": "item_123",
        "quantity": 2
      },
      "base_amount": 2000,
      "discount": 0,
      "total": 2000,
      "subtotal": 2000,
      "tax": 0
    }
  ],
  "fulfillment_address": {
    "name": "John Doe",
    "line_one": "123 Main St",
    "line_two": "Apt 4B",
    "city": "San Francisco",
    "state": "CA",
    "country": "US",
    "postal_code": "94105"
  },
  "fulfillment_options": [
    {
      "type": "shipping",
      "id": "shipping_fast",
      "title": "Express Shipping",
      "subtitle": "2-3 business days",
      "carrier": "Shipping Co",
      "subtotal": 150,
      "tax": 0,
      "total": 150
    }
  ],
  "fulfillment_option_id": "shipping_fast",
  "totals": [
    {
      "type": "subtotal",
      "display_text": "Subtotal",
      "amount": 2000
    },
    {
      "type": "fulfillment",
      "display_text": "Shipping",
      "amount": 150
    },
    {
      "type": "tax",
      "display_text": "Tax",
      "amount": 100
    },
    {
      "type": "total",
      "display_text": "Total",
      "amount": 2250
    }
  ],
  "messages": [],
  "links": []
}
```

## エージェンティック決済セッションの更新

項目、配送先住所、またはフルフィルメントオプションを変更して、既存のエージェンティック決済セッションを更新できます。

### リクエスト

リクエストに必要なパラメーターを指定します。

| パラメーター                      | タイプ                                                                                                           | 説明                        |
| --------------------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------- |
| **id**                      | `string`                                                                                                      | Checkout プロセスの一意の識別子。(必須) |
| **買い手**                     | `hash` (optional) [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#buyer)   | 買い手に関する情報。                |
| **items**                   | `array` (optional) [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#item)   | 購入する商品の配列を更新しました。         |
| **fulfillment\_address**    | `hash` (optional) [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#address) | 更新されたフルフィルメント住所。          |
| **fulfillment\_option\_id** | `string` (optional)                                                                                           | 選択したフルフィルメントオプションの識別子。    |

**リクエスト例:**

```json
PUT /checkouts/:id
{
  "items": [
    {
      "id": "item_123",
      "quantity": 3
    },
    {
      "id": "item_456",
      "quantity": 1
    }
  ],
  "fulfillment_address": {
    "name": "John Doe",
    "line_one": "456 Oak Ave",
    "city": "Los Angeles",
    "state": "CA",
    "country": "US",
    "postal_code": "90210"
  },
  "fulfillment_option_id": "shipping_fast"
}
```

### レスポンス

レスポンスは売り手から Checkout の現在の状態を返します。

| パラメーター                      | タイプ                                                                                                                 | 説明                                                                                                                              |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| **id**                      | `string`                                                                                                            | エージェンティック決済セッションの一意の識別子。(必須)                                                                                                    |
| **買い手**                     | `hash` (optional) [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#buyer)         | 買い手に関する情報。                                                                                                                      |
| **payment\_provider**       | `hash` (オプション) [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#payment-provider) | 決済代行業者の設定とサポートされている決済手段。                                                                                                        |
| **status**                  | `string`                                                                                                            | Checkout プロセスの現在のステータス。(必須)

  使用可能な値: `not_ready_for_payment` | `ready_for_payment` | `completed` | `canceled` | `in_progress` |
| **currency**                | `string`                                                                                                            | 小文字の 3 文字の ISO 通貨コード。(必須)                                                                                                       |
| **line\_items**             | `array` [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#line-item)               | Checkout プロセスの項目の配列。(必須)                                                                                                        |
| **fulfillment\_address**    | `hash` (optional) [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#address)       | 注文の配送先住所。                                                                                                                       |
| **fulfillment\_options**    | `array` [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#fulfillment-option)      | 利用可能な配送オプションとフルフィルメントオプション。(必須)                                                                                                 |
| **fulfillment\_option\_id** | `string` (optional)                                                                                                 | 現在選択されているフルフィルメントオプションの ID。                                                                                                     |
| **totals**                  | `array` [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#total)                   | 請求と割引の概要。(必須)                                                                                                                   |
| **messages**                | `array` [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#message)                 | Checkout プロセスに関連するメッセージまたは通知の配列。(必須)                                                                                            |
| **links**                   | `array` [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#link)                    | Checkout プロセスに関連するリンクの配列。(必須)                                                                                                   |

**レスポンス例:**

```json
{
  "id": "checkout_abc123",
  "buyer": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com",
    "phone_number": "+1234567890"
  },
  "payment_provider": {
    "provider": "stripe",
    "supported_payment_methods": ["card"]
  },
  "status": "ready_for_payment",
  "currency": "usd",
  "line_items": [
    {
      "id": "item_123",
      "item": {
        "id": "item_123",
        "quantity": 3
      },
      "base_amount": 3000,
      "discount": 0,
      "total": 3000,
      "subtotal": 3000,
      "tax": 0
    },
    {
      "id": "item_456",
      "item": {
        "id": "item_456",
        "quantity": 1
      },
      "base_amount": 500,
      "discount": 0,
      "total": 500,
      "subtotal": 500,
      "tax": 0
    }
  ],
  "fulfillment_address": {
    "name": "John Doe",
    "line_one": "456 Oak Ave",
    "city": "Los Angeles",
    "state": "CA",
    "country": "US",
    "postal_code": "90210"
  },
  "fulfillment_options": [
    {
      "type": "shipping",
      "id": "shipping_fast",
      "title": "Express Shipping",
      "subtitle": "2-3 business days",
      "carrier": "Shipping Co",
      "subtotal": 150,
      "tax": 0,
      "total": 150
    }
  ],
  "fulfillment_option_id": "shipping_fast",
  "totals": [
    {
      "type": "subtotal",
      "display_text": "Subtotal",
      "amount": 3500
    },
    {
      "type": "fulfillment",
      "display_text": "Shipping",
      "amount": 150
    },
    {
      "type": "tax",
      "display_text": "Tax",
      "amount": 100
    },
    {
      "type": "total",
      "display_text": "Total",
      "amount": 3750
    }
  ],
  "messages": [],
  "links": []
}
```

## Checkout の完了

決済を処理し、注文を作成することで Checkout プロセスを完了できます。

### リクエスト

リクエストに必要なパラメーターを指定します。

| パラメーター            | タイプ                                                                                                         | 説明                        |
| ----------------- | ----------------------------------------------------------------------------------------------------------- | ------------------------- |
| **id**            | `string`                                                                                                    | Checkout プロセスの一意の識別子。(必須) |
| **買い手**           | `hash` (optional) [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#buyer) | 買い手に関する情報。                |
| **payment\_data** | `hash` [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#payment-data)     | 取引を処理する決済手段の詳細。(必須)       |

**リクエスト例:**

```json
POST /checkouts/:id/complete
{
  "payment_data": {
    "token": "spt_123",
    "provider": "stripe",
    "billing_address": {
      "name": "John Doe",
      "line_one": "123 Main St",
      "line_two": "Apt 4B",
      "city": "San Francisco",
      "state": "CA",
      "country": "US",
      "postal_code": "94105"
    }
  }
}
```

### レスポンス

レスポンスは売り手から Checkout の現在の状態を返します。

| パラメーター                      | タイプ                                                                                                                 | 説明                                                                                                                              |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| **id**                      | `string`                                                                                                            | エージェンティック決済セッションの一意の識別子。(必須)                                                                                                    |
| **買い手**                     | `hash` (optional) [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#buyer)         | 買い手に関する情報。                                                                                                                      |
| **payment\_provider**       | `hash` (オプション) [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#payment-provider) | 決済代行業者の設定とサポートされている決済手段。                                                                                                        |
| **status**                  | `string`                                                                                                            | Checkout プロセスの現在のステータス。(必須)

  使用可能な値: `not_ready_for_payment` | `ready_for_payment` | `completed` | `canceled` | `in_progress` |
| **currency**                | `string`                                                                                                            | 小文字の 3 文字の ISO 通貨コード。(必須)                                                                                                       |
| **line\_items**             | `array` [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#line-item)               | Checkout プロセスの項目の配列。(必須)                                                                                                        |
| **fulfillment\_address**    | `hash` (optional) [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#address)       | 注文の配送先住所。                                                                                                                       |
| **fulfillment\_options**    | `array` [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#fulfillment-option)      | 利用可能な配送オプションとフルフィルメントオプション。(必須)                                                                                                 |
| **fulfillment\_option\_id** | `string` (optional)                                                                                                 | 現在選択されているフルフィルメントオプションの ID。                                                                                                     |
| **totals**                  | `array` [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#total)                   | 請求と割引の概要。(必須)                                                                                                                   |
| **messages**                | `array` [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#message)                 | Checkout プロセスに関連するメッセージまたは通知の配列。(必須)                                                                                            |
| **links**                   | `array` [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#link)                    | Checkout プロセスに関連するリンクの配列。(必須)                                                                                                   |

**レスポンス例:**

```json
{
  "id": "checkout_abc123",
  "buyer": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com",
    "phone_number": "+1234567890"
  },
  "status": "completed",
  "currency": "usd",
  "line_items": [
    {
      "id": "item_123",
      "item": {
        "id": "item_123",
        "quantity": 3
      },
      "base_amount": 3000,
      "discount": 0,
      "total": 3000,
      "subtotal": 3000,
      "tax": 0
    },
    {
      "id": "item_456",
      "item": {
        "id": "item_456",
        "quantity": 1
      },
      "base_amount": 500,
      "discount": 0,
      "total": 500,
      "subtotal": 500,
      "tax": 0
    }
  ],
  "fulfillment_address": {
    "name": "John Doe",
    "line_one": "456 Oak Ave",
    "city": "Los Angeles",
    "state": "CA",
    "country": "US",
    "postal_code": "90210"
  },
  "fulfillment_options": [
    {
      "type": "shipping",
      "id": "shipping_fast",
      "title": "Express Shipping",
      "subtitle": "2-3 business days",
      "carrier": "Shipping Co",
      "subtotal": 150,
      "tax": 0,
      "total": 150
    }
  ],
  "fulfillment_option_id": "shipping_fast",
  "totals": [
    {
      "type": "subtotal",
      "display_text": "Subtotal",
      "amount": 3500
    },
    {
      "type": "fulfillment",
      "display_text": "Shipping",
      "amount": 150
    },
    {
      "type": "tax",
      "display_text": "Tax",
      "amount": 100
    },
    {
      "type": "total",
      "display_text": "Total",
      "amount": 3750
    }
  ],
  "messages": [],
  "links": []
}
```

## Checkout をキャンセルする

必要に応じて既存のエージェンティック決済セッションをキャンセルできます。

### リクエスト

リクエストに必要なパラメーターを指定します。

| パラメーター | タイプ      | 説明                        |
| ------ | -------- | ------------------------- |
| **id** | `string` | Checkout プロセスの一意の識別子。(必須) |

**リクエスト例:**

```json
POST /checkouts/:id/cancel
{}
```

### レスポンス

レスポンスは売り手から Checkout の現在の状態を返します。

| パラメーター                      | タイプ                                                                                                                 | 説明                                                                                                                              |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| **id**                      | `string`                                                                                                            | エージェンティック決済セッションの一意の識別子。(必須)                                                                                                    |
| **買い手**                     | `hash` (optional) [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#buyer)         | 買い手に関する情報。                                                                                                                      |
| **payment\_provider**       | `hash` (オプション) [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#payment-provider) | 決済代行業者の設定とサポートされている決済手段。                                                                                                        |
| **status**                  | `string`                                                                                                            | Checkout プロセスの現在のステータス。(必須)

  使用可能な値: `not_ready_for_payment` | `ready_for_payment` | `completed` | `canceled` | `in_progress` |
| **currency**                | `string`                                                                                                            | 小文字の 3 文字の ISO 通貨コード。(必須)                                                                                                       |
| **line\_items**             | `array` [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#line-item)               | Checkout プロセスの項目の配列。(必須)                                                                                                        |
| **fulfillment\_address**    | `hash` (optional) [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#address)       | 注文の配送先住所。                                                                                                                       |
| **fulfillment\_options**    | `array` [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#fulfillment-option)      | 利用可能な配送オプションとフルフィルメントオプション。(必須)                                                                                                 |
| **fulfillment\_option\_id** | `string` (optional)                                                                                                 | 現在選択されているフルフィルメントオプションの ID。                                                                                                     |
| **totals**                  | `array` [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#total)                   | 請求と割引の概要。(必須)                                                                                                                   |
| **messages**                | `array` [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#message)                 | Checkout プロセスに関連するメッセージまたは通知の配列。(必須)                                                                                            |
| **links**                   | `array` [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#link)                    | Checkout プロセスに関連するリンクの配列。(必須)                                                                                                   |

**レスポンス例:**

```json
{
  "id": "checkout_abc123",
  "buyer": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "john.doe@example.com",
    "phone_number": "+1234567890"
  },
  "status": "canceled",
  "currency": "usd",
  "line_items": [
    {
      "id": "item_123",
      "item": {
        "id": "item_123",
        "quantity": 3
      },
      "base_amount": 3000,
      "discount": 0,
      "total": 3000,
      "subtotal": 3000,
      "tax": 0
    },
    {
      "id": "item_456",
      "item": {
        "id": "item_456",
        "quantity": 1
      },
      "base_amount": 500,
      "discount": 0,
      "total": 500,
      "subtotal": 500,
      "tax": 0
    }
  ],
  "fulfillment_address": {
    "name": "John Doe",
    "line_one": "456 Oak Ave",
    "city": "Los Angeles",
    "state": "CA",
    "country": "US",
    "postal_code": "90210"
  },
  "fulfillment_options": [
    {
      "type": "shipping",
      "id": "shipping_fast",
      "title": "Express Shipping",
      "subtitle": "2-3 business days",
      "carrier": "Shipping Co",
      "subtotal": 150,
      "tax": 0,
      "total": 150
    }
  ],
  "fulfillment_option_id": "shipping_fast",
  "totals": [
    {
      "type": "subtotal",
      "display_text": "Subtotal",
      "amount": 3500
    },
    {
      "type": "fulfillment",
      "display_text": "Shipping",
      "amount": 150
    },
    {
      "type": "tax",
      "display_text": "Tax",
      "amount": 100
    },
    {
      "type": "total",
      "display_text": "Total",
      "amount": 3750
    }
  ],
  "messages": [
    {
      "type": "info",
      "content_type": "plain",
      "content": "Checkout cancelled: Customer changed their mind"
    }
  ],
  "links": []
}
```

## データ構造

このセクションでは、Checkout プロセスに関連するデータ構造の概要を説明します。

### 買い手

買い手は、購入を開始する個人です。

| パラメーター            | タイプ                 | 説明                 |
| ----------------- | ------------------- | ------------------ |
| **first\_name**   | `string`            | 買い手の名。(必須)         |
| **last\_name**    | `string`            | 買い手の姓。(必須)         |
| **email**         | `string`            | 買い手のメールアドレス。**必須** |
| **phone\_number** | `string` (optional) | 買い手の電話番号。          |

### 商品

Item は、買い手が数量とともに購入をリクエストする製品またはサービスです。

| パラメーター       | タイプ       | 説明                           |
| ------------ | --------- | ---------------------------- |
| **id**       | `string`  | 項目の一意の識別子。(必須)               |
| **quantity** | `integer` | この Checkout で要求された項目の数量。(必須) |

### LineItem

LineItem には、Checkout に追加された項目に関する情報 (金額など) が含まれます。

| パラメーター           | タイプ                                                                                             | 説明             |
| ---------------- | ----------------------------------------------------------------------------------------------- | -------------- |
| **id**           | `string`                                                                                        | 項目の一意の識別子。(必須) |
| **item**         | `hash` [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#item) | 項目の詳細。(必須)     |
| **base\_amount** | `integer`                                                                                       | 項目の基本金額。(必須)   |
| **discount**     | `integer`                                                                                       | 項目の割引額。(必須)    |
| **total**        | `integer`                                                                                       | 項目の合計金額。(必須)   |
| **subtotal**     | `integer`                                                                                       | 項目の小計。(必須)     |
| **tax**          | `integer`                                                                                       | 項目の税額。(必須)     |

### 住所

Address は買い手の配送先住所または請求先住所を提供します。

| パラメーター           | タイプ                 | 説明                                  |
| ---------------- | ------------------- | ----------------------------------- |
| **name**         | `string`            | 商品がフルフィルメントされる個人の名前。(必須)            |
| **line\_one**    | `string` (optional) | 住所 (1 行目。番地、私書箱、会社名など)。             |
| **line\_two**    | `string` (optional) | 住所 2 行目 (建物や部屋番号など)。                |
| **city**         | `string`            | 市区町村、地区、郊外、町、村。(必須)                 |
| **state**        | `string`            | 州、郡、都道府県、地域。(必須)                    |
| **country**      | `string`            | 2 文字の国コード (ISO 3166-1 alpha-2)。(必須) |
| **postal\_code** | `string`            | 郵便番号。(必須)                           |

### PaymentData

PaymentData は、トークン化された値や決済代行業者など、買い手の決済詳細を提供します。

| パラメーター               | タイプ                                                                                                           | 説明                     |
| -------------------- | ------------------------------------------------------------------------------------------------------------- | ---------------------- |
| **token**            | `string`                                                                                                      | 決済認証情報への安全な参照。(必須)     |
| **provider**         | `string`                                                                                                      | 決済データの対象となる決済代行業者。(必須) |
| **billing\_address** | `hash` (optional) [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#address) | 決済手段の請求書先住所。           |

### 合計

Total は、全体的な合計のサマリーを提供します。

| パラメーター            | タイプ       | 説明                                                                                                                              |
| ----------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------- |
| **type**          | `enum`    | 合計のタイプ。(必須)

  可能な値: `items_base_amount` | `items_discount` | `subtotal` | `discount` | `fulfillment` | `tax` | `fee` | `total` |
| **display\_text** | `string`  | 合計の表示テキスト。(必須)                                                                                                                  |
| **amount**        | `integer` | 合計金額。(必須)                                                                                                                       |

### FulfillmentOption

フルフィルメントオプションは、配送またはデジタルのいずれかです。具体的な実装については、[ShippingFulfillmentOption](https://docs.stripe.com/agentic-commerce/protocol/specification.md#shipping-fulfillment-option) と [DigitalFulfillmentOption](https://docs.stripe.com/agentic-commerce/protocol/specification.md#digital-fulfillment-option) をご覧ください。

### ShippingFulfillmentOption

ShippingFulfillmentOption は、配送業者情報や配送時間など、配送フルフィルメントオプションのパラメーターを定義します。

| パラメーター                       | タイプ                 | 説明                                         |
| ---------------------------- | ------------------- | ------------------------------------------ |
| **type**                     | `enum`              | フルフィルメントオプションのタイプ。(必須)

  可能な値: `shipping` |
| **id**                       | `string`            | 配送フルフィルメントオプションの一意の識別子。(必須)                |
| **title**                    | `string`            | 配送フルフィルメントオプションのタイトル。(必須)                  |
| **subtitle**                 | `string` (optional) | 配送フルフィルメントオプションのサブタイトル。                    |
| **配送業者**                     | `string` (optional) | 配送フルフィルメントオプションの配送業者。                      |
| **earliest\_delivery\_time** | `string` (optional) | 配送フルフィルメントオプションの最も早い配送時間 (ISO 8601 形式)。    |
| **latest\_delivery\_time**   | `string` (optional) | 配送フルフィルメントオプションの最新配送時刻 (ISO 8601 形式)。      |
| **subtotal**                 | `integer`           | 配送フルフィルメントオプションの小計。(必須)                    |
| **tax**                      | `integer`           | 配送フルフィルメントオプションの税額。(必須)                    |
| **total**                    | `integer`           | 配送フルフィルメントオプションの合計。(必須)                    |

### DigitalFulfillmentOption

DigitalFulfillmentOption は、タイトルや価格情報など、デジタルフルフィルメントオプションのパラメーターを定義します。

| パラメーター       | タイプ                 | 説明                                          |
| ------------ | ------------------- | ------------------------------------------- |
| **type**     | `enum`              | フルフィルメントオプションのタイプ。(必須)

  使用可能な値: `digital` |
| **id**       | `string`            | デジタルフルフィルメントオプションの一意の識別子。(必須)               |
| **title**    | `string`            | デジタルフルフィルメントオプションのタイトル。(必須)                 |
| **subtitle** | `string` (optional) | デジタルフルフィルメントオプションのサブタイトル。                   |
| **subtotal** | `integer`           | デジタルフルフィルメントオプションの小計。(必須)                   |
| **tax**      | `integer`           | デジタルフルフィルメントオプションの税額。(必須)                   |
| **total**    | `integer`           | デジタルフルフィルメントオプションの合計。(必須)                   |

### PaymentProvider

PaymentProvider は、売り手がサポートする決済代行業者と利用可能な方法を定義します。

| パラメーター                          | タイプ      | 説明                                      |
| ------------------------------- | -------- | --------------------------------------- |
| **provider**                    | `string` | 売り手の決済代行業者。(必須)

  可能な値: `stripe`       |
| **supported\_payment\_methods** | `array`  | 売り手によって許可された決済手段。(必須)

  使用可能な値: `card` |

### メッセージ

メッセージは、情報メッセージまたはエラーメッセージです。

#### InfoMessage

InfoMessage は、タイプとコンテンツの詳細を示す情報メッセージを表します。

| パラメーター            | タイプ                 | 説明                                                      |
| ----------------- | ------------------- | ------------------------------------------------------- |
| **type**          | `enum`              | メッセージタイプを表す文字列値。

  使用可能な値: `info`                      |
| **param**         | `string` (optional) | RFC 9535 メッセージが参照するエージェンティック決済セッションのコンポーネントへの JSONPath。 |
| **content\_type** | `enum` (オプション)      | メッセージのコンテンツのタイプ。

  使用可能な値: `plain` | `markdown`        |
| **content**       | `string`            | メッセージのコンテンツ。                                            |

#### ErrorMessage

ErrorMessage はエラーメッセージを表し、タイプとコードの詳細が示されます。

| パラメーター            | タイプ                 | 説明                                                                                                                    |
| ----------------- | ------------------- | --------------------------------------------------------------------------------------------------------------------- |
| **type**          | `enum`              | メッセージタイプを表す文字列値。

  使用可能な値: `error`                                                                                   |
| **code**          | `enum`              | エラーのコード。

  使用可能な値: `missing` | `invalid` | `out_of_stock` | `payment_declined` | `requires_sign_in` | `requires_3ds` |
| **param**         | `string` (optional) | RFC 9535 メッセージが参照するエージェンティック決済セッションのコンポーネントへの JSONPath。                                                               |
| **content\_type** | `enum` (オプション)      | メッセージのコンテンツのタイプ。

  使用可能な値: `plain` | `markdown`                                                                      |
| **content**       | `string`            | メッセージのコンテンツ。                                                                                                          |

### エラー

Error は、Checkout プロセス中に発生したエラーに関連するパラメータを定義します。

| パラメーター      | タイプ                 | 説明                                                                                                                |
| ----------- | ------------------- | ----------------------------------------------------------------------------------------------------------------- |
| **type**    | `enum`              | エラーのタイプ。(必須)

  使用可能な値: `invalid_request` | `request_not_idempotent` | `processing_error` | `service_unavailable` |
| **code**    | `string`            | 実装で定義されたエラーコード。(必須)                                                                                               |
| **message** | `string`            | エラーのメッセージ。(必須)                                                                                                    |
| **param**   | `string` (optional) | RFC 9535 メッセージが参照するエージェンティック決済セッションのコンポーネントへの JSONPath。                                                           |

### Link

Link は、ポリシーと規約に関連するリンクのパラメーターを定義します。

| パラメーター   | タイプ      | 説明                                                                                      |
| -------- | -------- | --------------------------------------------------------------------------------------- |
| **type** | `enum`   | リンクのタイプを表す文字列値。(必須)

  可能な値: `terms_of_use` | `privacy_policy` | `seller_shop_policies` |
| **url**  | `string` | リンクの URL。(必須)                                                                           |

### 注文

Order は Checkout プロセスの結果を提供し、買い手に注文検索の詳細を提供します。

| パラメーター                    | タイプ      | 説明                               |
| ------------------------- | -------- | -------------------------------- |
| **id**                    | `string` | 注文の一意の識別子。(必須)                   |
| **checkout\_session\_id** | `string` | 注文が発生したエージェンティック決済セッションへの参照。(必須) |
| **permalink\_url**        | `string` | 注文のパーマリンク URL。(必須)               |

### イベント

Event は、注文の作成と更新に関連するイベントのパラメータを定義します。

| パラメーター   | タイプ                                                                                                         | 説明                                                         |
| -------- | ----------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| **type** | `enum`                                                                                                      | イベントのタイプ。(必須)

  使用可能な値: `order_created` | `order_updated` |
| **data** | `hash` [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#order-event-data) | 注文情報を含むイベントデータ。(必須)                                        |

### OrderEventData

OrderEventData には、注文イベントに関連するデータが含まれます。

| パラメーター                    | タイプ                                                                                                | 説明                                                                                                                |
| ------------------------- | -------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| **type**                  | `string`                                                                                           | 文字列値はイベントデータのタイプを表します。注文データには、値 `order` を使用します。(必須)                                                               |
| **checkout\_session\_id** | `string`                                                                                           | この注文を作成したエージェンティック決済セッションを識別する ID。(必須)                                                                            |
| **permalink\_url**        | `string`                                                                                           | この URL は注文を示しています。顧客はこの URL にアクセスし、メールアドレスを入力して注文の詳細を表示できます。(必須)                                                  |
| **status**                | `enum`                                                                                             | 注文の最新ステータスを表す文字列。(必須)

  使用可能な値: `created` | `manual_review` | `confirmed` | `canceled` | `shipped` | `fulfilled` |
| **refunds**               | `array` [:paymentLink:](https://docs.stripe.com/agentic-commerce/protocol/specification.md#refund) | 注文に対して発行された返金のリスト。(必須)                                                                                            |

### 返金

Refund は、完了した注文に関連する返金を管理するためのパラメーターを定義します。

| パラメーター     | タイプ       | 説明                                                         |
| ---------- | --------- | ---------------------------------------------------------- |
| **type**   | `enum`    | 返金のタイプ。(必須)

  使用可能な値: `store_credit` | `original_payment` |
| **amount** | `integer` | 返金額。(必須)                                                   |