コンテンツにスキップ
アカウント作成/サインイン
Stripe ドキュメントのロゴ
/
アカウントを作成サインイン
概要
アカウント管理
決済処理
プラットフォーム管理

AI エージェントでコンテキストに応じたショッピングを有効にする非公開プレビュー

AI チャットエージェントでビジネスが商品を販売できるようにする方法をご紹介します。

プライベートプレビュー

ChatGPT の Instant Checkout を含む AI エージェントによる商品販売や、買い手と事業者間の取引管理にエージェンティックコマースをご利用になる場合は、ウェイトリストに参加してください。

ビジネスに関する情報を共有する

プラットフォームと連結アカウントがコンテキストに応じたエージェント販売を行うように設定するには、以下の詳細を指定します。

  • プラットフォームの Stripe アカウント ID。
  • 連結アカウント ID。コンテキストに応じたエージェント販売を有効にする連結アカウント ID のリストを指定します。スプレッドシートまたはプレーンテキストのファイルに、1 行につき 1 つのアカウント ID を送信できます。

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

製品カタログを準備する

各連結アカウントの Stripe 製品カタログの仕様に準拠した CSV ファイルを作成します。Stripe は仕様を別途共有します。

Stripe にカタログデータをアップロードする

Stripe API を使用してフィードを送信します。更新は 15 分ごとに送信できます。

本番更新を有効にする前に、サンドボックスを使用して解析、フィールドマッピング、データ品質を検証します。

まず、Files API を使用して商品カタログ CSV をアップロードします。リクエストが成功すると、id を含む File オブジェクトが返されます。

  • 目的として data_management_manual_upload を指定します。
  • MIME タイプがファイル形式と一致していることを確認してください。使用できる形式は、CSV と TSV です。各行は 1 つの商品またはバリエーションを表します。
  • 最大ファイルサイズは 200 MB です。
Command Line
curl https://files.stripe.com/v1/files \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -H "Stripe-Account: {{CONNECTED_ACCOUNT_ID}}" \
  -F purpose=data_management_manual_upload \
  -F file="@/path/to/your/file.csv;type=text/csv"

次に、Data Management API を使用して ImportSet を作成します。このコールによりカタログ処理が開始され、ダッシュボードでデータを使用できるようになります。以下を含めます。

  • 返されたファイル id
  • プレビューヘッダー (Stripe-Version: 2025-09-30.clover;udap_beta=v1 など)
Command Line
curl https://api.stripe.com/v1/data_management/import_sets \
  -H "Stripe-Version: 2025-09-30.clover;udap_beta=v1" \
  -H "Stripe-Account: {{CONNECTED_ACCOUNT_ID}}" \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d file={{FILE_ID}} \
  --data-urlencode standard_data_format="product_catalog_feed"

フィードステータスの監視

Stripe はカタログデータを処理し、検証とクリーニングを行ってから、フォーマットのインデックスを作成します。Stripe はカタログデータを検証してクリーンアップし、インデックスを作成し、AI エージェント用のフォーマットに変換します。インポートセットのstatus フィールドを使用して、インデックス作成の進捗を監視します。ステータスはpending、failed、succeeded、succeeded_with_errors、pending_archive、archived のいずれかになります。

Command Line
curl https://api.stripe.com/v1/data_management/import_sets/{{IMPORT_SET_ID}} \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -H "Stripe-Account: {{CONNECTED_ACCOUNT_ID}}"

レスポンスには、ステータスとエラーが含まれます。

{
  "id": "impset_7MabcdZ8b617780e5145413",
  "object": "data_management.import_set",
  "created": 1643992696,
  "livemode": true,
  "result": {
    "errors": {
      "file": "file_234923sIENc",
      "row_count": 30
    },
    "rows_processed": 120,
    "successes": {
      "row_count": 90
    }
  },
  "status": "succeeded_with_errors"
}

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

  1. レスポンスで result.errors.file フィールドを探します。
  2. Files API を使用して、エラーファイルを ID で取得します。
  3. ダウンロードされた CSV には、stripe_error_message という名前の先頭列が設定された元のデータが含まれ、各行が失敗した理由が示されます。
Command Line
curl https://files.stripe.com/v1/files/{{ERROR_FILE_ID}}/contents \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:

API は、失敗した行のみを含む CSV ファイルを返します。各エラーを説明する stripe_error_message 列が含まれます。

購入への対応と注文のフルフィルメント

Stripe Webhook をリッスンして、AI チャットエージェントで行われた注文を監視します。

注文が確定されると、Stripe はフルフィルメントロジックを実行するためにサーバーが処理できる Webhook イベントを送信します。これらのイベントを受け入れ、処理し、承認するようにサーバーにエンドポイントを設定します。Stripe Webhook の導入とテストの手順については、Webhook ガイドを参照してください。

Stripe は checkout.session.completed と payment_intent.succeeded を送信します。フルフィルメントロジックがすでにこれらのイベントを処理している場合は、追加の導入変更は必要ありません。コンテキストに応じたエージェント販売のフルフィルメントロジックをカスタマイズできます (たとえば、注文確認メールで決済がエージェントを介して発生したことを通知するなど)。

const stripe = require('stripe')(process.env.STRIPE_SECRET_KEY);

// Use the secret provided by Stripe CLI for local testing
// or your webhook endpoint's secret
const endpointSecret = 'whsec_...';

app.post('/webhook', (request, response) => {
  const sig = request.headers['stripe-signature'];
  let event;

  try {
    event = stripe.webhooks.constructEvent(request.body, sig, endpointSecret);
  } catch (err) {
    response.status(400).send(`Webhook Error: ${err.message}`);
    return;
  }

  if (event.type === 'checkout.session.completed') {
    const session = event.data.object;
    // Fulfill the order using the session data
    fulfillCheckout(session.id);
  }

  response.status(200).send();
});

オプション手動によるキャプチャー

デフォルトでは、購入が行われるとすぐに決済がキャプチャーされます。手動キャプチャーを設定するには、ダッシュボードで設定します。手動キャプチャーを有効にすると、前のセクションで説明した Webhook で返された PaymentIntent でキャプチャーメソッドを呼び出します。

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl -X POST https://api.stripe.com/v1/payment_intents/pi_3MrPBM2eZvKYlo2C1TEMacFD/capture \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"

オプションCheckout カスタマイズフックを設定する

Stripe には、Checkout Session をカスタマイズできる 2 つのフックがあります。

  1. customize_checkout: Checkout Session の配送オプションと税金をカスタマイズします。
  2. finalize_checkout: Checkout Session のプラットフォーム手数料をカスタマイズし、必要に応じてセッションを手動で承認または拒否します。

Stripe に連絡して、これら 2 つのフックの URL を登録してください。

customize_checkout のリクエスト形式を表示します。

{
  type: string,
  id: string,
  livemode: boolean,
  // Connected account ID
  context?: string,
  // Request specific data
  data: {
    // Used by the seller to determine whether they can set manual tax rates on line items 
    automatic_tax: {
      enabled: boolean,
    },
    currency: string,
    line_item_details?: Array<{
      id: string,
      unit_amount: number,
      quantity: number,
      name: string,
      tax_rates: Array<string>
    }>,
    shipping_details?: {
      // Same as the shipping rate object described at https://docs.stripe.com/api/shipping_rates/object#shipping_rate_object
      shipping_rate?: {
        id: string,
        display_name?: string,
        tax_code?: string ,
        tax_behavior: 'unspecified' | 'included' | 'excluded',
        fixed_amount: {
          amount: number,
          currency: 'usd' | 'cad' | etc.,
          currency_options.<currency>: {
            amount: number,
            tax_behavior: 'unspecified' | 'included' | 'excluded',
          }
        },
        delivery_estimate?: {
          maximum: { unit: 'business_day' | 'day' | 'hour' | 'month' | 'year', value: number },
          minimum: { unit: 'business_day' | 'day' | 'hour' | 'month' | 'year', value: number }
        }
      },
      // Same as the shipping rate object described at https://docs.stripe.com/api/shipping_rates/object#shipping_rate_object
      shipping_rates?: Array<{
        id: string,
        display_name?: string,
        tax_code?: string,
        tax_behavior: 'unspecified' | 'included' | 'excluded',
        fixed_amount: {
          amount: number,
          currency: 'usd' | 'cad' | etc.,
          currency_options.<currency>: {
            amount: number,
            tax_behavior: 'unspecified' | 'included' | 'excluded',
          }
        },
        delivery_estimate?: {
          maximum: { unit: 'business_day' | 'day' | 'hour' | 'month' | 'year', value: number },
          minimum: { unit: 'business_day' | 'day' | 'hour' | 'month' | 'year', value: number }
        }
      },
      address?: {
        line1?: string,
        line2?: string,
        city?: string,
        state?: string,
        postal_code?: string,
        country?: string
      }
    },
    amount_total?: number,
    amount_subtotal?: number,
    total_details?: {
      amount_discount?: number,
      amount_shipping?: number,
      amount_tax?: number
    }
  }
}

customize_checkout の応答形式

{
  shipping_options?: Array<{
    // ID of the shipping rate, or data provided to create the shipping rate. Only provide one; not both
    shipping_rate?: string,
    shipping_rate_data: {
      display_name?: string,
      fixed_amount: {
        amount: number,
        currency: 'usd' | 'cad' | etc.,
      },
      tax_code?: string ,
      tax_behavior?: 'unspecified' | 'included' | 'excluded',
      // Same as the shipping rate object described at https://docs.stripe.com/api/shipping_rates/create#create_shipping_rate-delivery_estimate
      delivery_estimate?: {
        maximum: { unit: 'business_day' | 'day' | 'hour' | 'month' | 'year', value: number },
        minimum: { unit: 'business_day' | 'day' | 'hour' | 'month' | 'year', value: number }
      }
    },
  }>,
  line_items?: Array<{
    // Corresponding ID of the line item to update
    id: string,
    // IDs of the v1 tax rate that will apply to this line item
    tax_rates: Array<string>
  }>,
}

finalize_checkout のリクエスト形式

{
  type: string,
  id: string,
  livemode: boolean,
  // Connected account ID
  context?: string,
  // Request specific data
  data: {
    currency: string,
    line_items_details: Array<{
      id: string,
      unit_amount: number,
      quantity: number,
      name: string
    }>,
    payment_method_details?: {
      type: "card" | ...,
      card?: {
        brand: "amex" | "visa" | "master_card" | ...,
        country?: string,
        exp_month: number,
        exp_year: number,
        fingerprint?: string,
        funding: "credit" | "debit" | "prepaid" | "unknown",
        iin?: string,
        last4: string,
        wallet?: {
          type: "apple_pay" | "google_pay" | ...
        }
      }  
    },
    billing_details?: {
      name?: string,
      address?: {
        line1?: string,
        line2?: string,
        city?: string,
        state?: string,
        postal_code?: string,
        country?: string
      }
    },
    shipping_details?: {
      name?: string,
      address?: {
        line1?: string,
        line2?: string,
        city?: string,
        state?: string,
        postal_code?: string,
        country?: string
      },
    },
    email?: string,
    phone?: string,
    amount_total?: number,
    amount_subtotal?: number,
    total_details?: {
      amount_discount?: number,
      amount_shipping?: number,
      amount_tax?: number
    }
  }
}

finalize_checkout の応答形式を表示します。

{
  manual_approval_details?: {
    type: "approved" | "declined",
    declined?: {
      reason: string
    }
  },
  application_fee_details?: {
    application_fee_amount: number,
    transfer_data?: {
      amount?: number,
    }
  }
}

オプション埋め込みコンポーネント

メモ

この埋め込みコンポーネントは現在開発中です。コードスニペットは説明のみを目的としており、変更される可能性があります。

Stripe は、連結アカウントのエージェンティックコマースへのユーザー登録に役立つ埋め込みコンポーネントを提供しています。Stripe がオンラインで提供するこのコンポーネントを使用すると、連結アカウントは、どの AI エージェントが商品を販売できるかを管理し、エージェントプラットフォーム全体でビジネスを表示する方法をカスタマイズできます。

次のコード例は、プラットフォームがこの埋め込みコンポーネントを導入する方法を示しています。ダッシュボード機能を Web サイトに埋め込む方法の詳細については、Connect 埋め込みコンポーネントを始めるを参照してください。

// server.js
const stripe = require("stripe")(
  'sk_123',
  { apiVersion: 'YYYY-MM-DD'}
);

// POST /account_session_token
const accountSession = await stripe.accountSessions.create({
  account: '{{CONNECTED_ACCOUNT_ID}}',
  components: {
    agentic_commerce_settings: {
      enabled: true,
    },
  },
},
{
  apiVersion: `${STRIPE_API_VERSION}; embedded_connect_beta=v2`,
});

response.json({ accountSessionToken: accountSession.client_secret });
// App.jsx
import {
  ConnectAgenticCommerceSettings,
  ConnectComponentsProvider,
} from "@stripe/react-connect-js";
import { loadConnectAndInitialize } from "@stripe/connect-js";

const AgenticCommerce = () => {
  const [stripeConnectInstance] = React.useState(() => {
    const fetchClientSecret = async () => {
      const response = await fetch('/account_session', { method: "POST" });
      if (!response.ok) {
        const {error} = await response.json();
        console.log('An error occurred: ', error);
        return undefined;
      } else {
        const {client_secret: clientSecret} = await response.json();
        return clientSecret;
      }
    };

    return loadConnectAndInitialize({
      publishableKey: "pk_123",
      fetchClientSecret: fetchClientSecret,
    })
  });

  return (
    <div>
      <ConnectComponentsProvider connectInstance={stripeConnectInstance}>
        <ConnectAgenticCommerceSettings />
      </ConnectComponentsProvider>
    </div>
  )
}

オプション増分インベントリ更新を送信する

商品カタログのアップロードに加えて、Inventory Feed API を使用して個別の商品在庫の更新を送信できます。カタログのアップロードと同じアップロードプロセスを使用しますが、standard_data_forma を inventory_feed に設定します。

Command Line
# Step 1: Upload your CSV using the Files API
curl https://files.stripe.com/v1/files \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -H "Stripe-Account: {{CONNECTED_ACCOUNT_ID}}" \
  -F purpose=data_management_manual_upload \
  -F file="@/path/to/your/file.csv;type=text/csv"

# Step 2: Create an ImportSet object
curl https://api.stripe.com/v1/data_management/import_sets \
  -H "Stripe-Version: 2025-09-30.clover;udap_beta=v1" \
  -H "Stripe-Account: {{CONNECTED_ACCOUNT_ID}}" \
  -u 
sk_test_BQokikJOvBiI2HlWgH4olfQ2
: \
  -d file={{FILE_ID}} \
  --data-urlencode standard_data_format="inventory_feed"

オプション返金および不審請求の申し立ての処理

すでに PaymentIntents API またはCheckout Sessions API を使用している場合、既存の返金と不審請求の申し立ての導入では、コンテキストに応じたエージェント販売を変更する必要はありません。PaymentIntent は、コンテキストに応じたエージェント販売フローで引き続き作成されます。PaymentIntent ID を注文に関連付ける限り、返金と不審請求の申し立ての導入は引き続き機能します。

決済が成功した後、顧客がお客様のウェブサイトまたは顧客サービスから注文をキャンセルした場合、返金することができます。すでに Checkout Sessions または PaymentIntents API を使用している場合は、コンテキストに応じた代理販売では既存の返金するフローは変更されずに機能します。

ダッシュボードの取引ページから、ノーコードで返金と不審請求の申し立てを管理できます。

プログラムで返金を処理するには、Refunds API を導入して決済後のキャンセルまたは返金リクエストに対応します。