【ITニュース解説】How I built a Stripe payment-link API for AI agents

このニュース記事は、AIエージェントにインターネット上で商品購入やサービス登録などの支払いを行わせる際の課題と、その解決策としてStripeの支払いリンク機能を活用したAPI「Agent Checkout™」を構築した経緯について解説している。

AIエージェントは、ドメインの購入や証明書の更新、APIクレジットのチャージといった実務をこなすことができるが、従来のAIエージェントフレームワークでは、支払いが必要な段階で処理が進まないという共通の問題があった。この課題を解決するため、開発者はAPIを構築し、AIエージェントが支払いリンクを生成して人間のオペレーターに提示することで、安全かつ効率的な支払いを実現した。

このシステム設計において最も重要な原則は、AIエージェントがクレジットカード情報を一切扱わないことである。もしエージェントがクレジットカード番号などの機密情報に触れる機会があれば、その情報がログファイルやシステム記録の様々な場所に漏洩するリスクが高まる。そうなると、クレジットカード情報の取り扱いに関する非常に厳格なセキュリティ基準（PCI DSSなど）の適用範囲が広がり、システムの開発・運用に多大なコストとリスクが生じる。このアーキテクチャでは、エージェントが支払い情報にアクセスできないようにシステムそのものが設計されており、ルールやポリシーで制限するだけでなく、技術的な構造によって安全性が確保されている。

具体的な支払いフローは次のようになる。まず、AIエージェントは購入金額、購入品の説明、そして加盟店を識別する情報をAPIに送信する。このAPIはStripeの支払いリンクを生成し、そのURLをエージェントに返す。エージェントにとっての役割はここで完了し、その後の仕事は生成された支払いリンクを人間のオペレーターに提示することである。人間は受け取ったURLを開くと、Stripeが提供する安全な支払いページが表示され、そこで信頼できる方法で支払いを行う。支払いが完了したかどうかは、エージェントがAPIを定期的に確認するか、Stripeからの自動通知（Webhook）を受け取ることで知ることができる。

このシステムでは、人間が支払いプロセスに介入する「Operator-in-the-loop」という設計が意図的に採用されている。これは、AIエージェント単独での支払いに伴うリスク、例えば意図しない高額な支払いを防止するためである。人間が支払いを承認するステップは、不正行為の防止策として機能すると同時に、支払いの承認記録（監査証跡）としても重要な役割を果たす。これにより、すべての支払いが人間の明確な意思によって行われたことが保証される。

加盟店は、Stripe ConnectのOAuth機能を利用するか、制限付きのAPIキーを提供することで、自身のStripeアカウントをサービスに接続できる。顧客からの支払いは、このサービスを介することなく、直接加盟店のStripeアカウントに入金される。このサービス自体が顧客の資金を一時的に保持したり、出金を処理したりすることは一切ない。これは、資金管理に伴う複雑な法的・規制上の問題を避けるための意図的な設計である。プラットフォームは、Stripe Connectを介した取引手数料か、定額のサブスクリプション料金によって収益を得る。資金の流れは、顧客から加盟店へ直接というシンプルな構造を維持している。

システムを構築する上で特に注意が必要なのが「Webhookの検証」である。Stripeは、支払い完了などのイベントが発生した際に、登録されたURLへ自動通知（Webhook）を送るが、この通知は秘密鍵で署名されている。支払い完了の通知が届いた際には、その署名を検証し、通知が本当にStripeから送られたものであり、途中で改ざんされていないことを確認しなければならない。なぜなら、AIエージェントは悪意があるわけではないが、時として事実と異なる情報を報告することがあるため、エージェントが「支払いが完了した」と報告しても、それが常に真実とは限らないからだ。したがって、唯一の真実の源は、Stripeが署名したWebhook、またはStripeのAPIを直接呼び出して取得した情報である。エージェントが報告する状態は決して信用せず、署名された情報だけを信頼するべきだ。

実装上の具体的な注意点もいくつか挙げられている。 一つは、支払いリンク作成時の「冪等性キー（Idempotency keys）」の使用である。AIエージェントはネットワークの一時的な問題などで処理を再試行することがよくあるため、同じ購入意図に対して複数の支払いリンクが生成されるのを防ぐために、一意のキーを支払いリンク作成APIの呼び出しごとに渡す。もし同じキーでのリクエストが再度あった場合は、すでに生成済みのリンクを返すようにすることで、重複を回避する。 次に、すべての支払いリンクに有効期限を設定することである。デフォルトでは24時間とされている。有効期限を設けることで、人間が未完了の支払いリンクにいつまでも意識を向けるのを防ぎ、エージェントも期限切れの状態を人間に明確に説明できるようになる。 さらに、注文の文脈、例えばエージェントが何を購入しようとしていたか、どの実行プロセスで、どのオペレーターが関与したかといった情報は、エージェントのメモリに頼るのではなく、Stripeの支払いリンクの「メタデータ」フィールドに保存すべきである。数時間後にWebhook通知が来た際、このメタデータがあれば、その支払いがどのエージェントのどのタスクに関連するものだったかを正確に特定できる。AIエージェントは情報を忘れやすいが、メタデータは保持される。

このAPIはAIエージェントが利用することを前提としているため、APIドキュメントの形式も工夫されている。人間が読むための詳細なドキュメントとは異なり、「llms.txt」というファイルには、APIのベースURL、主要なエンドポイント、入出力のJSON形式、エラーコードとその意味、そして完全なcurlコマンドの例など、エージェントがAPIを呼び出すために必要な情報が簡潔に記述されている。これは、エージェントが機械的に情報を解析しやすいように最適化された形式である。

この「llms.txt」の作成には以下の三つの原則が守られている。第一に、APIを呼び出すために必要なすべての情報が「一つのファイルに一つの契約」として集約されていること。第二に、長々とした説明よりも、完全なリクエストとレスポンスの「例示」を重視すること。第三に、llms.txtはコードの一部として扱われ、「APIと同時にバージョン管理する」こと。これにより、APIの変更とドキュメントの間に齟齬が生じるのを防ぎ、エージェントが常に正しい情報を参照できるようにしている。

このサービスは、開発者がAIエージェントの実験を気軽に行えるよう、1日100リンクまで無料で利用でき、クレジットカード登録も不要である。提供されるツールは「create_checkout_link」という一つの機能に特化している。

最後に、未解決の課題として、AIエージェントが生成した支払いリンクが人間にクリックされなかった場合の最適な処理方法が挙げられている。現在はリンクを24時間で期限切れにしているが、クリックされなかったリンクに対する通知や、その情報をエージェントの計画にどう活用するかなど、より良い解決策が模索されている。