ACPによる販売者側の連携：チェックアウトセッション、委任トークン、安全な再試行

概要

2026年10月25日時点の情報である。本記事では、日付付きのACP 2026-04-17仕様スナップショットと、そのリリース変更履歴を使用する。連携前に、合意したAPIバージョン、支払いハンドラーのスキーマ、リリースノートを再確認する。古いウェブページやリポジトリの未リリース用ディレクトリにある例を、断りなく代用してはならない。

Agentic Checkout APIは、セッションの作成、更新、取得、完了、キャンセルをプログラムから行うためのチェックアウトインターフェースを販売者に提供する。カートの正として扱う状態は販売者が返す。エージェントは変更を要求し、その結果を購入者に提示できる一方、チェックアウトの計算と注文処理は販売者のバックエンドが担当する。

重要な理由

チェックアウトへの合意と支払い資格情報の委任は、別の操作である。Delegate Payment APIは、販売者の決済サービスプロバイダーが制限付きで利用できるよう、資格情報をトークン化する。レスポンスには、保管庫内のトークン識別子が含まれる。許可条件には、上限金額、通貨、チェックアウトセッション識別子、販売者識別子、有効期限が含まれ、文書に記載された利用理由はone_timeである。

このトークンは、エージェントに買い物を包括的に許可するものではない。販売者と決済プロバイダーは、合意したハンドラーを組み込み、その制約を強制する必要がある。防御的な実装の実務として、資格情報の収集とトークンの発行は専用の決済コンポーネント内で行い、モデルのプロンプトや通常のリクエストログには含めない。

適用方法

• セッション操作を公開する。 /checkout_sessionsでの作成、セッションリソースに対する取得と更新、および/completeと/cancelの操作を実装する。現在の合計額、履行情報、メッセージ、状態を返す。ready_for_payment、authentication_required、complete_in_progress、completedの区別を保つ。
• 支払い処理方式を合意する。 チェックアウトが提示するハンドラーを使い、そのhandler_idと支払い手段のスキーマに従って、完了処理の支払いデータを送信する。保管庫のトークンだけでは、完全なチェックアウト要求にはならない。その支払い経路を有効にする前に、プロバイダーがトークンを解釈できることを確認する。
• 連携を認証する。 セキュリティ文書は、HTTPSとBearerトークン認証を規定している。採用したAPI契約で必須とされるAPI-Versionヘッダーを指定し、認証済みの販売者とエージェントの関係に基づいてセッションへのアクセスを認可する。
• 安全な再試行を実装する。 このリリースでは、POSTリクエストにIdempotency-Keyが必須である。キーを再利用できるのは、操作とボディが同じ場合だけである。キーがなければidempotency_key_required、処理中の重複要求にはidempotency_in_flight、同じキーでボディが変わっていればidempotency_conflictが返る。
• 注文通知を検証する。 このリリースは、タイムスタンプと未加工のボディに対するMerchant-SignatureによるWebhook認証を定義し、リプレイ対策としてタイムスタンプの許容時間幅を確認する。ローカルの履行状態を変更する前に、認証された更新をチェックアウトと注文に紐付ける。

落とし穴

HTTPでの成功は、セッションの完了を意味しない。処理が中断した後は、直ちに別の購入を始めるのではなく、運用上の照合処理でチェックアウト、支払い、注文の各状態を比較すべきである。

古い文書では冪等性が任意と説明されていても、この日付付きリリースでは必須である。スキーマを固定し、この規則を明示的にテストする。トークン化、購入者の確認、支払いの承認、履行には、それぞれ独自の証拠が必要であり、会話上の成功メッセージだけから推定してはならない。