Principes de base de l'API Google Pay pour le Web

1. Introduction

Ce que vous allez faire

À la fin de cet atelier de programmation, vous disposerez d'un site Web viable minimum avec une intégration Google Pay fonctionnelle. Ce projet récupère un jeton de paiement qui peut être envoyé à un fournisseur de services de paiement pour traitement.

Points abordés

  • Charger et configurer l'API Google Pay
  • Afficher le bouton Google Pay et gérer les clics
  • Demander un jeton de paiement à Google Pay

Prérequis

  • Un éditeur de texte de votre choix pour modifier les fichiers HTML et JavaScript.
  • Le navigateur Web Google Chrome ou un autre moyen de tester un site Web local.
  • Pour la production, vous aurez besoin d'un merchantId Google Pay. L'inscription à la Google Pay & Wallet Console ne prend qu'une minute. Autant s'en occuper tout de suite.

Suivez le tutoriel à l'aide de Firebase Studio

Ouvrir dans Firebase Studio

2. Créer la page HTML

Créer des fichiers de projet

  1. Créez un dossier sur votre ordinateur et nommez-le gpay-web-101. Dans ce dossier, créez deux fichiers texte vides nommés index.html et main.js. La structure de votre répertoire doit se présenter comme suit :
    gpay-web-101/
  index.html
  main.js
  2. Ouvrez index.html dans l'IDE de votre choix et ajoutez le code suivant :
    <!doctype html>
<html lang="en">

<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>Google Pay API for Web 101</title>
</head>

<body>
  <div id="gpay-container"></div>
  <p>Transaction info and errors will be logged to the console.</p>
  <script type="text/javascript" src="main.js"></script>
  <script
    async src="https://pay.google.com/gp/p/js/pay.js"
    onload="onGooglePayLoaded()">
  </script>
</body>

</html>

Explication du code

  1. Un DIV vide est ajouté à la page avec l'ID gpay-container. Cet élément DOM sera l'élément parent dans lequel le bouton Google Pay sera ajouté. Vous pouvez positionner cet élément dans la mise en page de votre site Web, le cas échéant.
  2. La balise de script main.js est placée dans le DOM après l'élément gpay-container. Cela est nécessaire pour s'assurer que le DIV du conteneur est présent dans le DOM avant que main.js ne le recherche. De plus, le script est synchrone pour s'assurer qu'il est chargé avant pay.js, car la méthode onGooglePayLoaded() doit exister avant la fin du chargement. Il existe d'autres façons d'obtenir le même effet, mais nous ne les aborderons pas ici.
  3. Enfin, pay.js est chargé de manière asynchrone et configure onGooglePayLoaded() en tant que gestionnaire onload. Cette méthode sera définie dans main.js.

3. Configurer Google Pay

Une demande de paiement Google Pay nécessite un objet de requête. L'objet défini ici comme baseGooglePayRequest contient les paramètres communs minimaux pour toutes les requêtes. Des paramètres supplémentaires seront ajoutés en fonction de la demande effectuée, que nous examinerons dans cet atelier de programmation.

Ajoutez les constantes de configuration Google Pay au fichier main.js vide :

//=============================================================================
// Configuration
//=============================================================================

// The DOM element that the Google Pay button will be rendered into
const GPAY_BUTTON_CONTAINER_ID = 'gpay-container';

// Update the `merchantId` and `merchantName` properties with your own values.
// Your real info is required when the environment is `PRODUCTION`.
const merchantInfo = {
  merchantId: '12345678901234567890',
  merchantName: 'Example Merchant'
};

// This is the base configuration for all Google Pay payment data requests.
const baseGooglePayRequest = {
  apiVersion: 2,
  apiVersionMinor: 0,
  allowedPaymentMethods: [
    {
      type: 'CARD',
      parameters: {
        allowedAuthMethods: [
          "PAN_ONLY", "CRYPTOGRAM_3DS"
        ],
        allowedCardNetworks: [
          "AMEX", "DISCOVER", "INTERAC", "JCB", "MASTERCARD", "VISA"
        ]
      },
      tokenizationSpecification: {
        type: 'PAYMENT_GATEWAY',
        parameters: {
          gateway: 'example',
          gatewayMerchantId: 'exampleGatewayMerchantId'
        }
      }
    }
  ],
  merchantInfo
};

// Prevent accidental edits to the base configuration. Mutations will be
// handled by cloning the config using deepCopy() and modifying the copy.
Object.freeze(baseGooglePayRequest);

Explication du code

  1. Définissez la variable constante GPAY_BUTTON_CONTAINER_ID sur l'ID de l'élément DOM utilisé sur la page HTML comme conteneur parent du bouton Google Pay.
  2. Créez l'objet de configuration baseGooglePayRequest avec les paramètres pertinents pour votre application. Chacune des propriétés et valeurs est disponible dans la documentation de référence. Les valeurs affichées dans cet exemple peuvent ou non correspondre parfaitement à vos besoins. Examinez-les donc attentivement.
  3. Mettez à jour les propriétés merchantId et merchantName avec vos propres valeurs. Ces champs sont facultatifs lorsque l'environnement est TEST.

Ressources

4. Ajouter un client de paiement

Un client de paiement est utilisé pour effectuer des demandes de paiement et enregistrer des rappels. Dans cet atelier de programmation, nous n'effectuerons que des demandes de paiement. Vous pouvez également configurer PaymentDataCallbacks pour gérer les cas où les données de paiement ou l'autorisation ont changé. Toutefois, ces sujets avancés ne sont pas abordés dans cet atelier de programmation.

Ajoutez ce code client à la fin de main.js :

//=============================================================================
// Google Payments client singleton
//=============================================================================

let paymentsClient = null;

function getGooglePaymentsClient() {
  if (paymentsClient === null) {
    paymentsClient = new google.payments.api.PaymentsClient({
      environment: 'TEST',
      merchantInfo,
      // todo: paymentDataCallbacks (codelab pay-web-201)
    });
  }

  return paymentsClient;
}

Explication du code

  1. La variable paymentsClient contiendra l'instance du client une fois qu'elle aura été créée. La variable n'est pas accessible directement par notre code, mais toujours par la méthode getGooglePaymentsClient().
  2. La méthode getGooglePaymentsClient() vérifie si un client a déjà été instancié et renvoie cette instance. Si aucun n'a été instancié auparavant, un est créé, enregistré et renvoyé. Cette méthode garantit qu'une seule instance est créée et utilisée tout au long de la durée de vie de ce script.
  3. Pour instancier un client, la méthode PaymentsClient() est appelée. Dans cet exemple, nous indiquons au client que nous nous trouvons dans un environnement TEST. L'alternative est PRODUCTION. Cependant, TEST est la valeur par défaut et peut être omise.

5. Ajouter des assistants

Les fonctions d'assistance suivantes sont utilisées plus loin dans le script et ont été ajoutées dans le seul but d'améliorer la lisibilité et la gestion du code.

Ajoutez les fonctions d'assistance en bas de main.js :

//=============================================================================
// Helpers
//=============================================================================

const deepCopy = (obj) => JSON.parse(JSON.stringify(obj));

function renderGooglePayButton() {
  const button = getGooglePaymentsClient().createButton({
    onClick: onGooglePaymentButtonClicked
  });

  document.getElementById(GPAY_BUTTON_CONTAINER_ID).appendChild(button);
}

Explication du code

  1. deepCopy() est un utilitaire qui utilise la sérialisation et la désérialisation JSON pour créer une copie complète de l'objet fourni. C'est un moyen pratique de cloner des objets sans se soucier des références partagées.
  2. renderGooglePayButton() est un utilitaire qui appelle la méthode de bibliothèque createButton() pour afficher le bouton Google Pay. L'argument transmis est un ensemble d'options qui définissent le comportement du bouton, par exemple l'enregistrement de la fonction onGooglePaymentButtonClicked() pour gérer les clics sur le bouton.

6. Ajouter des gestionnaires d'événements

Dans ce script, nous configurons deux gestionnaires d'événements. Le premier est appelé lorsque la bibliothèque pay.js a fini de se charger, et le second lorsque l'utilisateur clique sur le bouton Google Pay.

Ajoutez les gestionnaires d'événements en bas de main.js :

//=============================================================================
// Event Handlers
//=============================================================================

function onGooglePayLoaded() {
  const req = deepCopy(baseGooglePayRequest);

  getGooglePaymentsClient()
    .isReadyToPay(req)
    .then(function(res) {
      if (res.result) {
        renderGooglePayButton();
      } else {
        console.log("Google Pay is not ready for this user.");
      }
    })
    .catch(console.error);
}

function onGooglePaymentButtonClicked() {
  // Create a new request data object for this request
  const req = {
    ...deepCopy(baseGooglePayRequest),
    transactionInfo: {
      countryCode: 'US',
      currencyCode: 'USD',
      totalPriceStatus: 'FINAL',
      totalPrice: (Math.random() * 999 + 1).toFixed(2),
    },
    // todo: callbackIntents (codelab gpay-web-201)
  };

  // Write request object to console for debugging
  console.log(req);

  getGooglePaymentsClient()
    .loadPaymentData(req)
    .then(function (res) {
      // Write response object to console for debugging
      console.log(res);
      // @todo pass payment token to your gateway to process payment
      // @note DO NOT save the payment credentials for future transactions
      paymentToken = res.paymentMethodData.tokenizationData.token;
    })
    .catch(console.error);
}

Explication du code

  1. onGooglePayLoaded() est appelé lorsque le script pay.js a fini de se charger, comme défini dans le fichier HTML. La méthode isReadyToPay() est appelée pour déterminer s'il faut afficher ou non le bouton Google Pay. Si le consommateur est prêt à payer (c'est-à-dire qu'il a ajouté un mode de paiement à son compte Google Wallet), le bouton Google Pay s'affiche.
  2. onGooglePaymentButtonClicked() est appelé lorsque l'utilisateur clique sur le bouton Google Pay. Cette méthode appelle la méthode de bibliothèque loadPaymentData(), qui permet de récupérer un jeton de paiement. Une fois que vous avez le jeton de paiement, vous l'envoyez à votre passerelle de paiement pour traiter la transaction. transactionInfo décrit la transaction qui doit être traitée lorsque l'utilisateur clique sur ce bouton.

7. Conclusion

Félicitations ! Vous avez terminé cet atelier de programmation. Vous avez appris à intégrer l'API Google Pay à un site Web.

Exécuter le projet

Tester avec Google Chrome

Dans le navigateur Web Google Chrome, ouvrez index.html en sélectionnant Fichier > Ouvrir un fichier… dans le menu principal de Chrome. Chrome exécutera main.js lorsque le projet sera ouvert de cette manière. Il est possible que d'autres navigateurs Web n'autorisent pas l'exécution de JavaScript.

– ou –

Tester avec un serveur Web local

Si Python est installé, exécutez python3 -m http.server à partir d'une invite de terminal dans le dossier racine pay-web-101.

$ cd /your/path/to/pay-web-101
$ python3 -m http.server
Serving HTTP on :: port 8000 (http://[::]:8000/) ...

Accédez ensuite à votre site à l'adresse http://localhost:8000.

Étapes suivantes

Ressources supplémentaires