Paiement intégré

L'intégration du paiement intégré permet d'intégrer votre page de paiement Web aux surfaces Google. Utilisez ce chemin si votre produit nécessite une logique complexe (par exemple, des personnalisations) que l'API Native ne peut pas prendre en charge. Vous allez implémenter une UI de paiement qui sera intégrée au parcours de paiement via un iframe.

Qu'est-ce que le paiement intégré ?

Le paiement intégré (EC, Embedded Checkout) permet à un hôte (comme la recherche Google ou un agent d'IA) d'afficher votre processus de paiement Web existant dans son application (à l'aide d'un iframe ou d'une bibliothèque WebView). Contrairement à une redirection Web standard, cela permet une communication bidirectionnelle. L'hôte peut "déléguer" des tâches spécifiques, comme la sélection d'une adresse enregistrée ou le paiement avec un identifiant stocké, pour offrir une expérience plus rapide et plus naturelle, tandis que vous restez le marchand officiel et gérez la création de la commande.

Checklist d'implémentation pour les marchands

Pour prendre en charge le paiement intégré, vous devez respecter les exigences suivantes dans votre API UCP et votre application de paiement frontend.

1. Activer la détection (API UCP)

Vous devez déclarer que votre processus de paiement est compatible avec l'extension intégrée dans vos réponses à l'API UCP.

  • Action : ajoutez l'objet de capacité dev.ucp.shopping.embedded_checkout à votre tableau de capacités de réponse UCP.
  • Exigence : incluez les URL des spécifications et du schéma.
  • Facultatif : si vous avez besoin d'une authentification (par exemple, un jeton JWT) pour charger le règlement, définissez auth.required sur "true".
"capabilities": [
  {
    "name": "dev.ucp.shopping.embedded_checkout",
    "version": "2026-01-11",
    "spec": "https://ucp.dev/specs/shopping/embedded_checkout",
    "config": {
        "auth": { "required": true }
    }
  }
]

2. Initialisation de l'URL basée sur l'identifiant (interface utilisateur)

Lorsque l'hôte charge votre continue_url, il ajoute des paramètres de requête spécifiques. Votre interface utilisateur doit les analyser immédiatement après le chargement.

  • Action : analyse les paramètres de requête d'URL suivants :
    • ec_version : version du protocole (par exemple, 2026-01-11).
    • ec_auth : (le cas échéant) validez le jeton d'authentification fourni par l'hôte si vous avez défini auth.required: true.
    • ec_delegate : liste d'actions séparées par une virgule que l'hôte souhaite gérer de manière native (par exemple, payment.credential, fulfillment.address_change, payment.instruments_change).

3. Établir la communication (interface)

La communication se fait à l'aide de postMessage au format JSON-RPC 2.0.

  • Action : implémentez un écouteur pour les événements message.
  • Exigence : Vous devez valider l'origine de chaque message pour vous assurer qu'elle correspond à l'hôte.
  • Compatibilité native : pour les hôtes d'applications natives, recherchez et utilisez les variables globales injectées (par exemple, window.EmbeddedCheckoutProtocolConsumer) si postMessage n'est pas disponible.

4. Effectuer l'établissement de liaison (interface)

Dès que votre page de paiement s'affiche, vous devez indiquer à l'hôte que vous êtes prêt et confirmer les délégations que vous acceptez.

  • Action : envoyez la requête ec.ready immédiatement après le chargement.
  • Charge utile : incluez un tableau delegate listant les fonctionnalités que vous acceptez de laisser l'hôte gérer.
  • Exemple : Si l'URL demandée est ec_delegate=payment.credential et que vous l'acceptez, incluez "payment.credential" dans la charge utile ec.ready.
// Example: Sending the ec.ready message
const hostWindow = window.parent;
hostWindow.postMessage(JSON.stringify({
  "jsonrpc": "2.0",
  "id": "ready_1",
  "method": "ec.ready",
  "params": {
    "delegate": ["payment.credential"] // List capabilities you accept to delegate
  }
}), "*");

5. Implémenter une logique de délégation (frontend)

Si vous avez accepté une délégation lors de l'établissement de la liaison, vous devez modifier le comportement de votre UI pour éviter les conflits.

  • Action : Masquez les éléments d'UI pertinents pour les tâches déléguées.
  • Exemple : Si fulfillment.address_change est délégué, masquez votre formulaire d'adresse et affichez un bouton "Modifier l'adresse" à la place.
  • Action : lorsque l'utilisateur clique sur ce bouton, envoyez un message _request (par exemple, ec.fulfillment.address_change_request) à l'hôte.
  • Action : Attendez la réponse de l'organisateur. La réponse contient les nouvelles données (par exemple, l'adresse sélectionnée).
  • Exigence : Mettez à jour l'état de votre paiement à l'aide d'un remplacement de type PUT (remplacez l'intégralité de la section d'objet) en fonction des données renvoyées par l'hôte.
// Example: requesting payment credential
hostWindow.postMessage(JSON.stringify({
  "jsonrpc": "2.0",
  "id": "req_1",
  "method": "ec.payment.credential_request",
  "params": {
      "checkout": currentCheckoutState // Pass the full current checkout object
  }
}), "*");

6. Envoyer des mises à jour de l'état et du cycle de vie (interface)

Vous devez tenir l'hôte informé de l'état du paiement afin qu'il puisse mettre à jour son UI ou gérer les erreurs.

  • Action : envoi de notifications (messages sans ID) lorsque l'état change :
    • ec.start : lorsque le règlement est entièrement visible.
    • ec.line_items.change : si le contenu ou le total du panier sont modifiés.
    • ec.buyer.change : si les informations sur l'acheteur sont modifiées.
    • ec.complete : lorsque la commande a bien été passée.
    • ec.error : si une erreur critique se produit.

7. Appliquer la sécurité (serveur/en-têtes)

Vous devez vous assurer que votre page de paiement ne peut pas être intégrée par des acteurs malveillants.

  • Action : implémentez les en-têtes Content Security Policy (CSP).
  • Exigence : définissez frame-ancestors <host_origin>; pour autoriser l'intégration uniquement par des hôtes de confiance.
  • Navigation : logique de bloc qui empêche l'utilisateur de quitter le parcours de paiement (par exemple, supprimez les liens "Continuer les achats" qui redirigent vers votre page d'accueil). Des exceptions sont autorisées pour la validation 3DS ou les redirections de paiement tiers.