Intégration marchande avec ACP : sessions de passage en caisse, jetons délégués et relances sûres

Ce que c'est

État au 25 octobre 2026. Cet article s’appuie sur la version datée du 2026-04-17 de la spécification ACP et sur son journal des modifications. Vérifier à nouveau la version d’API convenue, les schémas des gestionnaires de paiement et les notes de version avant l’intégration. Ne pas leur substituer implicitement des exemples issus d’une ancienne page du site ou du répertoire du dépôt contenant les versions non publiées.

L’Agentic Checkout API fournit au marchand une interface de passage en caisse accessible par programmation : créer une session, la mettre à jour ou la consulter, la finaliser ou l’annuler. Le marchand renvoie l’état du panier qui fait autorité. Un agent peut demander des modifications et présenter le résultat à l’acheteur, tandis que le backend du marchand reste responsable des calculs du passage en caisse et du traitement des commandes.

Pourquoi c'est important

L’accord sur le passage en caisse et la délégation des justificatifs de paiement sont deux opérations distinctes. La Delegate Payment API transforme un justificatif en jeton pour une utilisation encadrée par le prestataire de services de paiement du marchand. Sa réponse contient un identifiant de jeton de coffre-fort. L’autorisation d’utilisation précise un montant maximal, une devise, un identifiant de session de passage en caisse, un identifiant de marchand et une échéance ; le motif d’utilisation documenté est one_time.

Ce jeton n’accorde pas à l’agent une permission générale de faire des achats. Le marchand et le prestataire de paiement doivent intégrer le gestionnaire convenu et faire respecter ses contraintes. À titre de mesure de protection dans l’implémentation, réserver la collecte des justificatifs et l’émission des jetons à des composants de paiement dédiés, hors des prompts du modèle et des journaux ordinaires de requêtes.

Comment l'appliquer

• Exposer les opérations de session. Implémenter la création sur /checkout_sessions, la consultation et les mises à jour sur la ressource de session, ainsi que les opérations /complete et /cancel. Renvoyer les totaux actuels, les informations d’exécution de la commande, les messages et l’état. Préserver la distinction entre ready_for_payment, authentication_required, complete_in_progress et completed.
• Négocier le traitement du paiement. Utiliser le gestionnaire annoncé lors du passage en caisse et envoyer les données de paiement nécessaires à la finalisation selon son handler_id et son schéma d’instrument de paiement. Un jeton de coffre-fort ne constitue pas à lui seul une demande complète de passage en caisse. Confirmer que le prestataire sait interpréter le jeton avant d’activer ce mode de paiement.
• Authentifier l’intégration. La documentation de sécurité impose HTTPS et l’authentification par jeton porteur. Fournir l’en-tête API-Version requis par le contrat choisi ; autoriser l’accès aux sessions dans le cadre de la relation authentifiée entre marchand et agent.
• Mettre en œuvre des relances sûres. Cette version exige Idempotency-Key pour les requêtes POST. Ne réutiliser une clé que pour la même opération et le même corps. L’absence de clé produit idempotency_key_required ; un doublon d’une opération en cours produit idempotency_in_flight ; un corps modifié sous la même clé produit idempotency_conflict.
• Vérifier les notifications de commande. Cette version définit l’authentification des webhooks par Merchant-Signature, portant sur l’horodatage et le corps brut, avec une vérification de la fenêtre temporelle pour empêcher le rejeu. Relier les mises à jour authentifiées à la session de passage en caisse et à la commande avant de modifier l’état local d’exécution de la commande.

Pièges

Un succès HTTP ne signifie pas que la session est finalisée. Après une interruption, un processus opérationnel de rapprochement doit comparer les états du passage en caisse, du paiement et de la commande plutôt que de lancer immédiatement un nouvel achat.

Cette version datée rend l’idempotence obligatoire, alors que des documentations antérieures la décrivent comme facultative. Fixer les versions des schémas et tester explicitement cette règle. La tokenisation, la confirmation de l’acheteur, l’autorisation de paiement et l’exécution de la commande exigent chacune leurs propres preuves ; aucune ne doit être déduite du seul message de réussite d’une conversation.