Cycle de vie du checkout UCP : les 6 états à gérer

Les six états d'un checkout UCP, les transitions autorisées, le traitement des messages et le passage sûr vers la commande.

Publiée le 23 août 2026 . Rattachée à le guide d'implémentation UCP.

Un checkout UCP n’est pas un simple formulaire. C’est une machine à états qui permet à une plateforme et à un marchand de savoir si la transaction peut avancer, exige une action du client ou doit être abandonnée.

En bref

La spécification définit 6 états de checkout.

messages explique les corrections ou validations attendues.

Seul ready_for_complete autorise une finalisation programmée.

Quels sont les six états ?

La spécification Checkout définit incomplete, requires_escalation, ready_for_complete, complete_in_progress, completed et canceled.

État	Signification	Action de la plateforme
`incomplete`	informations manquantes ou corrigeables	lire `messages`, mettre à jour
`requires_escalation`	intervention du client nécessaire	ouvrir `continue_url`
`ready_for_complete`	données suffisantes	appeler Complete Checkout
`complete_in_progress`	traitement marchand en cours	attendre ou relire l’état
`completed`	commande créée	utiliser la ressource Order
`canceled`	session invalide ou expirée	créer une nouvelle session

Le champ ucp.status ne remplace pas cet état métier. Il discrimine la forme de la réponse : success indique une ressource attendue, error une réponse d’erreur. Une implémentation doit donc lire les deux niveaux.

Comment traiter `incomplete` ?

incomplete signifie qu’une mise à jour par API reste possible. La plateforme inspecte le tableau messages, corrige le champ pointé, puis envoie Update Checkout. Les chemins de champ utilisent JSONPath, ce qui permet de rattacher précisément une erreur à une adresse, une ligne ou une option de livraison.

La sévérité recoverable confirme que l’agent peut résoudre le problème. Une rupture de stock sur une ligne peut par exemple conduire à ajuster la quantité. Il ne faut pas ouvrir immédiatement une interface humaine si une correction déterministe reste possible.

Quand passer la main au client ?

Les sévérités requires_buyer_input et requires_buyer_review contribuent à l’état requires_escalation. La première réclame une information inaccessible par l’API. La seconde impose une revue ou une autorisation, par exemple pour une règle réglementaire.

Dans les deux cas, la plateforme utilise continue_url. Cette URL doit reprendre un état conservé côté serveur. Elle ne doit pas exposer dans son chemin l’intégralité du checkout ou des données sensibles.

Pourquoi isoler la phase de finalisation ?

ready_for_complete signifie que les données nécessaires sont présentes. La plateforme peut alors appeler Complete Checkout. Le marchand passe à complete_in_progress pendant le traitement, puis à completed si la commande est créée.

Cette séparation évite de confondre une réponse réseau avec la réussite commerciale. Un délai après Complete Checkout ne justifie jamais de créer une nouvelle transaction sans relire l’état et réutiliser la même clé d’idempotence. Le protocole prévoit précisément cette protection contre les doubles effets.

Les avertissements ne sont pas tous facultatifs

Un message warning peut être une simple notice ou une disclosure. Une notice doit être affichée mais peut être écartée. Une disclosure doit apparaître près du composant concerné et ne peut être masquée ou supprimée automatiquement.

Cette distinction doit être conservée dans l’interface de l’agent. Réduire tous les warnings à du texte secondaire peut rendre un parcours techniquement valide mais non conforme aux obligations de présentation décrites par le marchand.

Tests minimaux avant production

chaque état est représenté dans les tests d’intégration ;
une erreur recoverable conduit à Update Checkout ;
une sévérité requires_* conduit à un handoff ;
Complete Checkout n’est jamais appelé depuis incomplete ;
un timeout de finalisation déclenche une lecture, pas une nouvelle commande ;
canceled produit une nouvelle session au lieu de ressusciter l’ancienne.

La séparation entre exploration et achat est détaillée dans Panier UCP ou checkout. La vue d’ensemble technique reste disponible dans le guide d’implémentation UCP.

Sources

Revenir à le guide d'implémentation UCP · Toutes les notes · Read in English