Note de référence

Payment handlers UCP : spécification, instrument et PSP

Payment handlers UCP : contenu, négociation et différence entre spécification de traitement, instrument de paiement et prestataire PSP.

Publiée le 1 août 2026 . Rattachée à le paiement agentique.

Dans le manifeste /.well-known/ucp, un registre porte tout le poids de la transaction : payment_handlers. La spécification en donne une définition qui mérite d’être lue littéralement, parce qu’elle inverse l’intuition de la plupart des équipes e-commerce.

Payment Handlers are specifications (not entities) that define how payment instruments are processed.

Des spécifications, pas des entités. Un payment handler ne dit pas « je passe par tel prestataire ». Il dit « voici la façon dont ce type d’instrument est traité chez moi ». La différence n’est pas cosmétique, et elle a des conséquences directes sur l’architecture et sur les contrats.

Ce que contient une entrée

Chaque gestionnaire déclaré combine six champs, d’après la spécification 2026-04-08 :

Champ	Rôle
`id`	identifiant du gestionnaire
`version`	version de la spécification de traitement
`spec`	URL de la spécification suivie
`schema`	schéma de validation associé
`available_instruments`	instruments effectivement acceptés
`config`	paramètres propres au marchand

La séparation entre spec et available_instruments est le cœur du dispositif. La première dit comment on traite. La seconde dit ce qu’on accepte aujourd’hui. Un marchand peut donc suivre une spécification de traitement large tout en n’ouvrant qu’un sous-ensemble d’instruments, puis élargir sans changer de spécification.

Pourquoi « spécification » et pas « prestataire »

Le modèle habituel du e-commerce couple l’acceptation au fournisseur : on branche un PSP, et la liste des moyens de paiement disponibles découle de son catalogue. Migrer de PSP suppose alors de refaire l’intégration, et souvent de reprendre le tunnel.

UCP déplace le contrat d’un cran. Ce que l’agent lit, c’est la manière dont le paiement se déroule, pas l’identité de celui qui l’exécute. La conséquence pratique : changer de prestataire ne change pas nécessairement le manifeste, tant que la spécification de traitement déclarée reste la même. L’agent continue de voir le même contrat, la plomberie change dessous.

C’est une décision d’architecture de protocole cohérente avec le reste d’UCP, où le marchand reste la source de vérité. Elle a un corollaire moins confortable : c’est au marchand, et non à son PSP, de garantir que le comportement déclaré correspond au comportement réel. Une déclaration optimiste se paiera en échecs de négociation côté agent.

Ce que la spécification ne dit pas

Il faut être net sur les limites de ce que le manifeste établit, parce que c’est là que se logent les mauvaises surprises.

Le manifeste déclare un contrat technique de traitement. Il n’attribue pas la responsabilité en cas de litige, il ne définit pas qui supporte une contestation, et il n’énonce pas de règle de partage du risque de fraude. Ces questions relèvent des règles des réseaux et des contrats d’acquisition, pas du protocole. Le socle d’autorisation sur lequel elles s’appuient est décrit sur la page AP2.

La spécification contient en revanche un principe de cadrage explicite, relevé dans les implémentations de référence : un manifeste représente un seul marchand, précisément pour garder la responsabilité et la propriété clairement attribuées. Un opérateur de place de marché qui voudrait exposer plusieurs vendeurs derrière un manifeste unique va donc à contre-courant du modèle.

Comment ça se combine avec les rails existants

UCP déclare le traitement ; les rails agent-aware fournissent l’instrument et la preuve d’autorisation. Les deux couches se complètent au lieu de se concurrencer.

AP2 apporte les mandats signés qui prouvent l’autorisation de l’utilisateur.
Visa Intelligent Commerce et Mastercard Agent Pay apportent des identifiants de carte liés à un agent, côté réseau.
Du côté ACP, la fonction équivalente est portée par une spécification de paiement délégué distincte de la spécification de checkout, visible dans le découpage OpenAPI du dépôt de référence.

Lire payment_handlers comme un choix de PSP est donc une erreur de niveau. C’est un choix de contrat de traitement, en amont du choix de fournisseur.

Trois questions à poser avant de déclarer

La spécification déclarée décrit-elle ce que le tunnel fait réellement ? Y compris sur les cas non nominaux : autorisation partielle, ajustement de montant, remboursement.
available_instruments reflète-t-il l’acceptation en production ? Un instrument déclaré mais refusé en pratique produit un échec en fin de parcours, au pire moment.
Le versionnement du gestionnaire est-il aligné sur le cycle de release ? La négociation UCP retient la version commune la plus élevée : publier une version que la production ne sert pas encore crée un écart silencieux.

Pour la mécanique de négociation qui exploite ces déclarations, voir la note sur le manifeste UCP. Pour le panorama des rails, voir le paiement agentique.

Sources

Revenir à le paiement agentique · Toutes les notes · Read in English