x402 v2のHTTP通信を実装する：ヘッダー、ファシリテーター、決済

概要

2026年10月25日時点の情報である。ここではx402プロトコルのバージョン2と、そのHTTPバインディングを説明する。デプロイ前に両仕様と採用するスキームを再確認すること。プロトコルのバージョンだけでは、実装の細部まで固定されない。RFC 9110はHTTP 402を将来の利用のために予約している。このステータスコード自体は、相互運用可能な支払い手順を定めていない。

x402はその手順を追加する。クライアントがリソースを要求すると、リソースサーバーが支払い要件を提示し、ファシリテーターが/verifyと/settleを通じて検証と決済を実行できる。サーバー自身がこの機能を運用してもよい。ファシリテーターは、選択したスキームとネットワークに対応している必要がある。

重要な理由

HTTPバインディングでは、base64でエンコードしたJSONを3つのヘッダーで送受信する。サーバーからの支払い要求にはPAYMENT-REQUIRED、クライアントからの支払いペイロードにはPAYMENT-SIGNATURE、決済結果にはPAYMENT-RESPONSEを使う。支払い要求の正規の格納先はヘッダーであり、クライアントは便宜的に提供されるJSONレスポンスボディに依存すべきではない。

コア仕様では、支払い承認の検証と資金の移動を分けている。既定のauthorizationフローでは、リソースの処理前に検証し、処理後に決済する。upfrontやescrowなど、ほかに定義されているフローでは、処理前に資金を確保する。したがって、検証の成功だけでは決済が行われた証拠にならない。

適用方法

• クライアントの処理を明確に実装する。 PaymentRequiredを解析し、acceptsから対応可能な項目を選び、署名前に金額、資産、ネットワーク、受取人を支出ポリシーと照合する。生成したペイロードはPAYMENT-SIGNATUREで送信する。未知の支払いフローは、その効果を推測せずに拒否する。
• サーバー側の検証を実装する。 要件を提示し、返された支払い承認がその要件を満たすか検証する。検証と決済は、選択したフローが定める順序に従う。決済結果はPAYMENT-RESPONSEで返し、照合のためにトランザクション識別子とネットワークを保存する。
• ブラウザー向けの基盤設定を確認する。 クロスオリジンのクライアントに対しては、CORSでPAYMENT-REQUIREDとPAYMENT-RESPONSEを公開し、プリフライトでPAYMENT-SIGNATUREを許可する。コマンドラインからの確認では、これらのブラウザー制約は検証できない。
• 結果が不確かな場合に対処する。 文書に記載されたsettlement_pendingという結果は、ブロードキャスト済みのトランザクションが今後確定する可能性を示す。別の支払いを行うべきか判断する前に、そのトランザクション識別子を使って状態を照合する。
• レビュー用チェックリストを使う。 統合作業の実務として、価格設定、署名、検証、決済、提供をどのコンポーネントが担当するか記録する。エージェントに支出権限を付与する前に、支払い拒否、ファシリテーターの利用不能、レスポンス消失を本番以外の環境で試す。

落とし穴

あらゆる402レスポンスを支出の許可とみなすのは、販売者からの要求とユーザーの承認を混同している。ユーザーの承認は別途管理する。コア仕様は、クライアントの予算管理を明示的に対象外としている。

運用上の確認に備え、支払い結果とリソースの提供は別々の記録として保持する。支払い済みなのに提供されていない要求は、別の支払い承認を発行する前に調査する。これらの記録管理の推奨事項は実装上の実務であり、HTTPが自動返金やアプリケーション処理の厳密に1回だけの実行を提供するという意味ではない。