# カスタム連携を構築する

Agentic Commerce Suite を使用して、サードパーティの処理事業者を通じてエージェンティック決済を受け付けます。

> Agentic Commerce Suite (ACS) は、米国で利用できます。独自の決済 API エンドポイントを構築し、サードパーティーの決済代行業者でエージェント型決済を処理する場合は、この連携を使用できます。アクセスをリクエストし、エンドポイントのアカウント登録を行うには、[ウェイトリストに登録](https://go.stripe.global/agentic-commerce-contact-sales)してください。

Agentic Commerce Suite (ACS) を使用すると、単一の実装でエージェントを通じて商品を販売できます。ACS でカスタム実装を構築し、サードパーティの決済代行業者で決済を処理するには、Stripe がコマースバックエンドに送信するリクエストと、バックエンドが返すレスポンスの形式を定義するリバース API を実装します。エージェントが決済リクエストを Stripe 経由でルーティングすると、Stripe はお客様に代わってこれらのエンドポイントを呼び出します。

これにより、単一の実装でエージェントを通じて商品を販売でき、エージェントごとの設定を不要にできます。エージェントが決済フローを完了したら、エージェントから受け取った Shared Payment Token を認証情報に変換し、サードパーティの決済代行業者で決済を処理します。
ACS Seller API (See full diagram at https://docs.stripe.com/agentic-commerce/for-sellers/custom)
## Before you begin

Stripe がお客様のカスタムエンドポイントをアカウント登録したら、Stripe ダッシュボードの[エージェンティックコマース](https://dashboard.stripe.com/agentic-commerce)に移動します。このフローでは、[Stripe プロフィール](https://docs.stripe.com/get-started/account/profile.md)の作成と、使用するエージェントのアカウント登録リクエストを順に行えます。

[ワークベンチ](https://docs.stripe.com/workbench.md)の Blueprints を使用して、[サンドボックス](https://docs.stripe.com/sandboxes.md)でリバース API リクエストの受信をテストすることをお勧めします。

- 無効な配送先住所を指定して、`UpdateSession` のリバース API リクエストをテストし、エラー検証メッセージが正しく表示されることを確認します。
- 特定の決済データを使用して、`CompleteSession` のリバース API リクエストをテストし、注文作成ロジックを確認します。

カスタムの明細項目、購入者の詳細、フルフィルメント先住所、その他のフィールドを含むリクエストペイロードを設定して、テストケースに合わせることができます。本番環境に移行する前に、決済フローが想定どおりに更新されること、送料の計算が正確であること、決済の確認が正常に完了することを確認してください。

エージェントを通じて商品を販売する準備ができたら、[エージェント利用規約](https://stripe.com/legal/ssa-services-terms#stripe-agentic-commerce-seller-services-preview)を確認し、ダッシュボードでエージェントのアカウント登録をリクエストします。Stripe がエージェントに承認リクエストを送信し、エージェントが承認する必要があります。エージェントを通じた販売を一時停止または停止するには、ダッシュボードでエージェントを無効にしてください。

## Optional: エージェントと商品データを共有する

Stripe を介してエージェント間で商品データを共有するには、商品データを Stripe にアップロードすると、Stripe が承認済みのエージェントに商品詳細を転送できます。

[Stripe product feed spec](https://docs.stripe.com/agentic-commerce/product-feed.md) に従った CSV ファイルを作成できます。

### Stripe に商品データをアップロードする

商品データはダッシュボードまたは API からアップロードします。データを最新の状態に保つため、商品データは 1 日 1 回アップロードし、在庫と価格については更新頻度の高い差分更新を送信してください。

> Stripe は、フィードのアップロードを独立した非同期タスクとして処理します。アップロードが送信した順序どおりに処理または完了されることは保証されません。複数のファイルを短時間に連続してアップロードすると、後からアップロードしたファイルが先に完了することがあります。

#### API

Stripe API を使用して、商品データ CSV をアップロードします。本番更新を有効にする前に、サンドボックスを使用して解析、フィールドマッピング、データ品質を検証することをお勧めします。

> [制限付き API キー](https://docs.stripe.com/keys.md#create-restricted-api-key)を使用する場合、**商品カタログのインポート**の書き込み権限が必要です。この権限がない場合、API リクエストは `403` エラーを返します。

### インポートを作成する

`ProductCatalogImport` を作成するには、[商品カタログインポート API](https://docs.stripe.com/api/v2/commerce/product-catalog-imports.md) を使用します。リクエストが成功すると、[ProductCatalogImport オブジェクト](https://docs.stripe.com/api/v2/commerce/product-catalog-imports/object.md)が `awaiting_upload` 状態で返されます。レスポンスの `status_details.awaiting_upload.upload_url.url` フィールドには、ファイルアップロード用の署名付き URL が含まれます。

```curl
curl -X POST https://api.stripe.com/v2/commerce/product_catalog/imports \
  -H "Authorization: Bearer <<YOUR_SECRET_KEY>>" \
  -H "Stripe-Version: 2026-05-27.preview" \
  --json '{
    "feed_type": "product",
    "mode": "upsert",
    "metadata": {
        "file_name": "march_11_2026_product_upload.csv"
    }
  }'
```

```json
{
  "id": "pcimprt_xxx",
  "object": "v2.commerce.product_catalog_import",
  "created": "2026-03-26T00:35:01.000Z",
  "feed_type": "product",
  "status": "awaiting_upload",
  "status_details": {
    "awaiting_upload": {
      "upload_url": {
        "expires_at": "2026-03-26T00:40:02.000Z",
        "url": "https://stripeusercontent.com/files/us-west-2/upload/wksp_xxx"
      }
    }
  },
  "livemode": true
}
```

### CSV をアップロードする

> 署名済みアップロード URL は 5 分後に有効期限が切れます。URL が期限切れになる前に CSV をアップロードしてください。URL が期限切れになった場合は、新しい `ProductCatalogImport` を作成して新しいアップロード URL を取得します。

署名済み URL に CSV をアップロードしてください。ファイルは CSV 形式で、各行が 1 つの商品またはバリアントを表している必要があります。ファイルサイズは最大 4 GB です。

```curl
curl -X PUT \
  -H "Content-Type: text/csv" \
  --data-binary @"/path/to/your/file.csv" \
  "{{PRESIGNED_URL}}"
```

Stripe がファイルを受信すると、インポートは `awaiting_upload` から `processing` に移行します。Stripe はファイルを検証し、項目を取り込みます。

### フィードステータスを監視し、エラーを解決する

Stripe は商品データを処理し、検証とクリーンアップを行い、AI エージェントに送信できる形式でインデックスを作成します。インデックス作成の進捗状況は、次の 2 つの方法で監視できます。

#### API

`GET` リクエストを使用してインポートオブジェクトをポーリングし、`status` フィールドを確認します。オブジェクトが最終状態 (`succeeded`、`succeeded_with_errors`、または `failed`) になるまで、ポーリングを続けます。

```curl
curl https://api.stripe.com/v2/commerce/product_catalog/imports/{{PRODUCTCATALOGIMPORT_ID}} \
  -H "Authorization: Bearer <<YOUR_SECRET_KEY>>" \
  -H "Stripe-Version: 2026-05-27.preview"
```

インポートがエラーなしで完了すると、`succeeded` になります。ファイルが構造的には有効でも、行レベルの検証に問題がある場合、インポートは `succeeded_with_errors` になります。インポートを完了できない場合 (たとえば、ファイルがアップロードされなかった、読み取り不能である、内部エラーが発生したなどの理由で) は、`failed` になります。

インポートのステータスが `succeeded_with_errors` の場合は、エラーファイルをダウンロードできます。

1. レスポンスの `status_details.succeeded_with_errors.error_file.url` フィールドを確認します。
1. 有効期限が切れる前に、その URL から CSV を直接ダウンロードします。
1. CSV には失敗した行のみが含まれ、先頭の `stripe_error_message` 列で各エラーが説明されます。

> エラーファイル URL の有効期限は 5 分後に切れます。新しい URL を取得するには、[取得エンドポイント](https://docs.stripe.com/api/v2/commerce/product-catalog-imports/retrieve.md)を再度呼び出してください。

#### Webhook

商品データのインデックス作成が完了すると、Stripe は最終状態を示すウェブフックイベントを送信します。`v2.commerce.product_catalog.imports.succeeded`、`v2.commerce.product_catalog.imports.succeeded_with_errors`、`v2.commerce.product_catalog.imports.failed` の各イベントをリッスンするエンドポイントを設定します。各イベントには `v2.commerce.product_catalog_import` オブジェクトが含まれます。手順について詳しくは、[ウェブフックガイド](https://docs.stripe.com/webhooks.md)を参照してください。

`v2.commerce.product_catalog.imports.succeeded` ウェブフックペイロードの例を次に示します。

```javascript
{
  "id": "evt_65THl3VA5Zt5cTqbP16T9R4DRrSQbEWmWeLUx7WmOR8B",
  "object": "v2.core.event",
  "type": "v2.commerce.product_catalog.imports.succeeded",
  "created": "2026-03-26T00:40:00.000Z",
  "livemode": true,
  "reason": null,
  "related_object": {
    "id": "pcimprt_61THl3VA5Zt5cTqbP16T9R4DRrSQbEWmWeLUx7WmOR8K",
    "type": "v2.commerce.product_catalog.imports",
    "url": "/v2/commerce/product_catalog/imports/pcimprt_61THl3VA5Zt5cTqbP16T9R4DRrSQbEWmWeLUx7WmOR8K"
  },
  "changes": {
    "before": {"status": "PROCESSING"},
    "after": {"status": "SUCCEEDED"}
  },
  "data": {}
}
```

ウェブフックにはインポートオブジェクト全体は含まれません。`related_object.url` を使用して取得します。

```curl
curl https://api.stripe.com/v2/commerce/product_catalog/imports/pcimprt_61THl3VA5Zt5cTqbP16T9R4DRrSQbEWmWeLUx7WmOR8K \
  -H "Authorization: Bearer <<YOUR_SECRET_KEY>>" \
  -H "Stripe-Version: 2026-05-27.preview"
```

インポートのステータスが `succeeded_with_errors` の場合は、エラーファイルをダウンロードできます。

1. レスポンスの `status_details.succeeded_with_errors.error_file.url` フィールドを確認します。
1. 有効期限が切れる前に、その URL から CSV を直接ダウンロードします。
1. CSV には失敗した行のみが含まれ、先頭の `stripe_error_message` 列で各エラーが説明されます。

> エラーファイル URL の有効期限は 5 分後に切れます。新しい URL を取得するには、取得エンドポイントを再度呼び出してください。

#### ダッシュボード

商品データの CSV をアップロードするには、ダッシュボードの[フィード履歴](https://dashboard.stripe.com/agentic-commerce/feed-history)ページに移動します。

## 決済作成フックを設定する

顧客が注文したい意思を示すと、エージェントはお客様に決済リクエストを送信します。リクエストを処理して現在の決済フローを返せば、エージェントは合計金額や配送方法などの利用可能なオプションを顧客に表示できます。必要な情報が不足している場合、決済フローは未完了のままです。

#### リクエスト

```json
POST api.seller.com/agentic/checkouts
{
  created: Timestamp,
  currency: "usd",
  // currently limited to single item checkouts
  line_items: [
    {
      sku_id: "sku_123",
      quantity: 2
    }
  ],
  buyer: {
    first_name: "John",
    last_name: "Doe",
    email: "john.doe@example.com",
    phone_number: "+1234567890"
  },
  fulfillment_details: {
     contact: {
        name: "Jane Doe",
        email: "jane.doe@example.com",
        phone_number: "+14155552671"
      },
      address: {
        "line_one": "123 Main St",
        "line_two": "Apt 4B",
        "city": "San Francisco",
        "state": "CA",
        "country": "US",
        "postal_code": "94105"
      }
  },
  agent_details: {
     network_profile: "profile_agent", // agent's Stripe provided unique id
     display_name: "Agent"
  }
}

```

#### レスポンス

```json
{
  id: "checkout_123", // unique checkout identifier
  currency: "usd",
  status: "incomplete" (Enum: "incomplete | ready_for_payment | requires_escalation | processing | completed | canceled"),
  buyer: {
    first_name: "John",
    last_name: "Doe",
    email: "john.doe@example.com",
    phone_number: "+1234567890"
  },
  fulfillment_details: {
    contact: {
        name: "Jane Doe",
        email: "jane.doe@example.com",
        phone_number: "+14155552671"
      },
    address: {
      "line_one": "123 Main St",
      "line_two": "Apt 4B",
      "city": "San Francisco",
      "state": "CA",
      "country": "US",
      "postal_code": "94105"
    }
  },
  line_items: [
    {
      id: "sku_123",
      item: {
        id: "prod_abc123",
        name: "Shampoo",
        description: "Shampoo for curly hair",
        images: ["https://seller.com/images/shampoo.jpg"],
        unit_amount: 5000
      },
      quantity: 2,
      base_amount: 10000,  // pre-discount amount in cents
      discount: 1000,      // total discount applied
      subtotal: 9000,      // after discount, before tax
      tax: 720,            // tax amount
      total: 9720          // final line item total
    }
  ],
  fulfillment_options: [  // available shipping or delivery methods
    {
      type: "shipping",
      id: "ship_standard_001",
      title: "Standard Shipping",
      subtitle: "5-7 business days",
      carrier: "USPS",
      earliest_delivery_time: "2026-01-20T00:00:00Z",  // ISO 8601
      latest_delivery_time: "2026-01-22T23:59:59Z",
      subtotal: 500,
      tax: 40,
      total: 540
    },
    {
      type: "shipping",
      id: "ship_express_001",
      title: "Express Shipping",
      subtitle: "2-3 business days",
      carrier: "FedEx",
      earliest_delivery_time: "2026-01-15T00:00:00Z",
      latest_delivery_time: "2026-01-16T23:59:59Z",
      subtotal: 1500,
      tax: 0,
      total: 1500
    },
  ],
  fulfillment_option_id?: "ship_standard_001", // Implement default selected shipping option, if any
  totals: [  // itemized cost breakdown
    {
      type: "items_base_amount",
      display_text: "Items",
      amount: 10000
    },
    {
      type: "discount",
      display_text: "Discount",
      amount: -1000
    },
    {
      type: "subtotal",
      display_text: "Subtotal",
      amount: 9000
    },
    {
      type: "fulfillment",
      display_text: "Shipping",
      amount: 0  // at this step, if shipping option is not yet selected, no shipping cost to show
    },
    {
      type: "tax",
      display_text: "Sales Tax",
      amount: 720
    },
    {
      type: "total",
      display_text: "Total",
      amount: 9720
    },
    {
      type: "packing_fee",
      display_text: "Gift Wrap",
      amount: 100
    },
  ],
}
```

## 決済更新フックの設定

エージェントは決済フローを更新して、項目を変更したり、フルフィルメントオプションを選択したり、住所を更新したりできます。更新のたびに合計金額を再計算し、在庫の有無を確認します。決済に必要な情報がすべて含まれている場合は、`ready_for_payment` としてマークします。

#### リクエスト

```json
POST api.seller.com/agentic/checkouts/:id
{
    fulfillment_option_id?: "ship_express_001", // updated shipping option
}

```

#### レスポンス

```json
{
  id: "checkout_123", // unique checkout identifier
  currency: "usd",status: "ready_for_payment" (Enum: "incomplete | ready_for_payment | requires_escalation | processing | completed | canceled"),
  buyer: {
    first_name: "John",
    last_name: "Doe",
    email: "john.doe@example.com",
    phone_number: "+1234567890"
  },
  fulfillment_details: {
    contact: {
        name: "Jane Doe",
        email: "jane.doe@example.com",
        phone_number: "+14155552671"
      },
    address: {
      "line_one": "123 Main St",
      "line_two": "Apt 4B",
      "city": "San Francisco",
      "state": "CA",
      "country": "US",
      "postal_code": "94105"
    }
  },
  line_items: [
    {
      id: "sku_123",
      item: {
        id: "prod_abc123",
        name: "Shampoo",
        description: "Shampoo for curly hair",
        images: ["https://seller.com/images/shampoo.jpg"],
        unit_amount: 5000
      },
      quantity: 2,
      base_amount: 10000,  // pre-discount amount in cents
      discount: 1000,      // total discount applied
      subtotal: 9000,      // after discount, before tax
      tax: 720,            // tax amount
      total: 9720          // final line item total
    }
  ],
  fulfillment_options: [  // available shipping or delivery methods
    {
      type: "shipping",
      id: "ship_standard_001",
      title: "Standard Shipping",
      subtitle: "5-7 business days",
      carrier: "USPS",
      earliest_delivery_time: "2026-01-20T00:00:00Z",  // ISO 8601
      latest_delivery_time: "2026-01-22T23:59:59Z",
      subtotal: 500,
      tax: 40,
      total: 540
    },
    {
      type: "shipping",
      id: "ship_express_001",
      title: "Express Shipping",
      subtitle: "2-3 business days",
      carrier: "FedEx",
      earliest_delivery_time: "2026-01-15T00:00:00Z",
      latest_delivery_time: "2026-01-16T23:59:59Z",
      subtotal: 1500,
      tax: 0,
      total: 1500
    },
  ],fulfillment_option_id?: "ship_express_001", // Implement default selected shipping option, if any
  totals: [  // itemized cost breakdown
    {
      type: "items_base_amount",
      display_text: "Items",
      amount: 10000
    },
    {
      type: "discount",
      display_text: "Discount",
      amount: -1000
    },
    {
      type: "subtotal",
      display_text: "Subtotal",
      amount: 9000
    },
    {
      type: "fulfillment",
      display_text: "Shipping",amount: 1500  // updated shipping cost
    },
    {
      type: "tax",
      display_text: "Sales Tax",
      amount: 720
    },
    {
      type: "total",
      display_text: "Total",
      amount: 9720
    },
    {
      type: "packing_fee",
      display_text: "Gift Wrap",
      amount: 100
    },
  ],
}
```

## 決済確認フックの設定

エージェントが決済を確定すると、Stripe は決済データとともに確認用エンドポイントを呼び出します。エンドポイントでは、SPT を受信し、それを使用して決済認証情報を取得し、代行業者に決済を記録する、という 3 つのステップを処理する必要があります。

### SPT を受け取る

エージェントが買い手の決済情報を収集して決済を確定すると、確認フックは [SPT](https://docs.stripe.com/api/shared-payment/granted-token.md) を受け取ります。SPT は、特定の使用および有効期限の制限のもとで、エージェントからお客様の [Stripe プロフィール](https://docs.stripe.com/get-started/account/profile.md) に付与される、顧客の決済手段に対するスコープ付きの権限です。

```json
POST api.seller.com/agentic/checkouts/:id/confirm
{
  payment_data: {
    token: "spt_123",  // Stripe SharedPaymentToken ID
    provider: "stripe",
    billing_address?: {  // optional
      line1?: string,
      city?: string,
      state?: string,
      postal_code?: string,
      country?: string
    }
  },
  risk_details: {
    client_device_metadata_details: {
      user_agent: "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"
      ip_address: 1.2.3.4
    }
  }
}
```

### SPT を使用する

[SPT resolve](https://docs.stripe.com/api/v1/shared_payment/granted_tokens/resolve.md) を使用してネットワーク認証情報を取得し、お客様の決済代行業者に送信します。

```bash
curl --request POST \
  --url https://api.stripe.com/v1/shared_payment/granted_tokens/:id/resolve \
  --header 'Authorization: Bearer sk_XXX' \
  --header 'Content-Type: application/x-www-form-urlencoded'
```

> 認証情報のタイプは `payment_method_details.credentials.type` に表示され、`agentic_token` または `dpan` のいずれかです。
> 
> カードネットワークと連携して、Stripe は Mastercard の Agent Pay や Visa のインテリジェントコマースプログラムなどのネットワークプログラムを通じて発行されたトークンを、お客様に代わって使用する場合があります。Stripe は、関連する取引のためにそれらのトークンをプロビジョニングして処理するため、要求されたデータをカードネットワークに送信します。

```json
{
  id: "spt_123",
  object: "shared_payment.granted_token",
  created: 1234567890,
  deactivated_at: null,
  deactivated_reason: null,
  livemode: true,
  shared_metadata: {},
  payment_method_details: {
    type: "card",
    card: {
      credentials?: {
        type: "dpan" || "agentic_token",
        // if type is agentic_token
        agentic_token?: {
          number?: string,
          exp_month?: string,
          exp_year?: string,
          cryptogram?: {
            value: string,
            type: "CAVV" | "TAVV" | "DCVV",
            eci?: string
          },
          encrypted?: {
            encryption_type: "RSA",
            encryption_block: string,
            encryption_block_fields: string,
            key_id: string
          }
        },
        // if type is dpan
        dpan?: {
          number?: string,
          exp_month?: string,
          exp_year?: string,
          cryptogram?: {
            value: string,
            type: "CAVV" | "TAVV" | "DCVV",
            eci?: string
          },
          encrypted?: {
            encryption_type: "RSA",
            encryption_block: string,
            encryption_block_fields: string,
            key_id: string
          }
        }
      },
      brand: "visa",
      country: "US",
      display_brand: "visa",
      exp_month: 9,
      exp_year: 2029,
      fingerprint: "dyRcYjZNxnHpC51l",
      funding: "credit",
      last4: "5627",
      networks: {
        available: ["visa"],
        preferred: null
      },
      wallet: null
    }
  },
  usage_details: {
    amount_captured: {
      value: 1000,
      currency: "usd"
    }
  },
  usage_limits: {
    currency: "usd",
    expires_at: 1234567890,
    max_amount: 10000
  },
  agent_details: {
    name: string,
    network_business_profile: "profile_1234"
  }
}
```

### 決済を記録する

決済代行業者で決済をキャプチャーしたら、[決済](https://docs.stripe.com/api/payment-record/report.md)を記録し、決済フローを確定します。

```curl
curl https://api.stripe.comv1/payment_records/report_payment \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d "payment_method_details[shared_payment_granted_token]=spt_123" \
  -d "amount_requested[value]=1000" \
  -d "amount_requested[currency]=usd" \
  -d initiated_at=54646747 \
  -d outcome=guaranteed \
  -d "guaranteed[amount][value]=1000" \
  -d "guaranteed[amount][currency]=usd" \
  -d "guaranteed[final_capture]=true" \
  -d "guaranteed[guaranteed_at]=54646747" \
  -d "processor_details[type]=custom" \
  -d "processor_details[custom][payment_reference]=auth_order_id_1"
```

### 決済を確定して注文を処理する

```json
{
    // status must be in_progress or completed, or you must return an error
    status: "in_progress" | "completed",
    order: {
      id: string,
      permalink_url: string,
    },
    metadata?: Hash
}
```

## 決済取得フックの設定

エージェントが最新の決済状態を取得すると、Stripe は現在の完全な決済状態を送信し、お客様はその状態に対する変更を返します。何も変更されていない場合は、更新を行わずに現在の状態を返すことができます。

#### リクエスト

```bash
GET api.seller.com/agentic/checkouts/:id
```

#### レスポンス

```json
{
    status: "in_progress",
}
```

## See also

- [Shared Payment Token](https://docs.stripe.com/agentic-commerce/concepts/shared-payment-tokens.md)