Mettre en œuvre les échanges HTTP x402 v2 : en-têtes, facilitateurs et règlement

Ce que c'est

État au 25 octobre 2026. Cet article décrit la version 2 du protocole x402 et sa transposition sur HTTP. Vérifier à nouveau les deux spécifications et le schéma choisi avant tout déploiement ; une version de protocole ne fixe pas à elle seule tous les détails de mise en œuvre. La RFC 9110 réserve HTTP 402 à un usage futur : le code d’état ne fournit en lui-même aucune procédure de paiement interopérable.

x402 apporte cette procédure. Un client demande une ressource, le serveur de ressources fournit les exigences de paiement, et un facilitateur peut effectuer la vérification et le règlement via /verify et /settle. Le serveur peut assurer lui-même ces fonctions. Le facilitateur doit prendre en charge le schéma et le réseau choisis.

Pourquoi c'est important

La transposition sur HTTP transporte du JSON encodé en base64 dans trois en-têtes : PAYMENT-REQUIRED pour la demande de paiement du serveur, PAYMENT-SIGNATURE pour la charge utile de paiement du client et PAYMENT-RESPONSE pour les résultats du règlement. L’en-tête de demande est l’emplacement de référence ; un client ne doit pas dépendre d’un corps de réponse JSON fourni par commodité.

La spécification principale distingue la vérification de l’autorisation du transfert des fonds. Dans le flux authorization, utilisé par défaut, la vérification précède l’exécution de la ressource et le règlement lui succède. D’autres flux définis, dont upfront et escrow, engagent les fonds avant l’exécution. Une vérification réussie ne suffit donc pas à prouver que le règlement a eu lieu.

Comment l'appliquer

• Concevoir explicitement le comportement du client. Analyser PaymentRequired, sélectionner une entrée prise en charge dans accepts, puis vérifier son montant, son actif, son réseau et son destinataire au regard de la politique de dépenses avant de signer. Envoyer la charge utile obtenue via PAYMENT-SIGNATURE. Rejeter les flux de paiement inconnus plutôt que d’en supposer les effets.
• Mettre en œuvre les contrôles côté serveur. Fournir les exigences et valider l’autorisation reçue par rapport à celles-ci. Respecter l’ordre de vérification et de règlement du flux choisi. Renvoyer le résultat du règlement dans PAYMENT-RESPONSE ; conserver son identifiant de transaction et son réseau pour le rapprochement.
• Vérifier l’infrastructure pour les navigateurs. Pour les clients d’une autre origine, exposer PAYMENT-REQUIRED et PAYMENT-RESPONSE via CORS et autoriser PAYMENT-SIGNATURE lors de la requête préliminaire. Un test en ligne de commande ne couvre pas ces restrictions du navigateur.
• Gérer l’incertitude. Le résultat documenté settlement_pending signifie qu’une transaction diffusée peut encore être confirmée. Effectuer le rapprochement à partir de son identifiant de transaction avant de décider si un autre paiement est justifié.
• Utiliser une liste de contrôle pour la revue. Dans le cadre de l’intégration, consigner le composant responsable de la tarification, de la signature, de la vérification, du règlement et de la fourniture de la ressource. Tester les paiements refusés, les facilitateurs indisponibles et les réponses perdues dans un environnement hors production avant d’autoriser un agent à dépenser.

Pièges

Considérer toute réponse 402 comme une permission de dépenser revient à confondre une demande du vendeur avec l’autorisation de l’utilisateur. Gérer cette autorisation séparément. La spécification principale exclut explicitement la gestion du budget côté client.

Pour la revue opérationnelle, conserver des enregistrements distincts du résultat du paiement et de la fourniture de la ressource. Examiner toute demande payée mais non satisfaite avant d’émettre une autre autorisation. Ces recommandations de traçabilité relèvent des pratiques de mise en œuvre ; elles ne signifient pas que HTTP assure des remboursements automatiques ou une exécution de l’application exactement une fois.