Nozioni di base sull'API Google Pay per il web

1. Introduzione

Cosa creerai

Al termine di questo codelab, avrai un sito web minimo funzionante con un'integrazione di Google Pay. Questo progetto recupera un token di pagamento che può essere inviato a un fornitore di servizi di pagamento per l'elaborazione.

Obiettivi didattici

  • Come caricare e configurare l'API Google Pay
  • Come visualizzare il pulsante Google Pay e gestire i clic
  • Come richiedere un token di pagamento da Google Pay

Che cosa ti serve

  • Un editor di testo a tua scelta per modificare i file HTML e JavaScript.
  • Il browser web Google Chrome o un altro modo per testare un sito web locale.
  • Per la produzione, avrai bisogno di un merchantId Google Pay. La registrazione alla console di Google Pay e Wallet richiede solo un minuto, quindi tanto vale occuparsene subito.

Segui le istruzioni utilizzando Firebase Studio

Apri in Firebase Studio

2. Crea la pagina HTML

Creare file di progetto

  1. Crea una cartella sul computer denominata gpay-web-101 e al suo interno crea due file di testo vuoti denominati index.html e main.js.La struttura delle directory dovrebbe essere simile alla seguente:
    gpay-web-101/
  index.html
  main.js
  2. Apri index.html nell'IDE che preferisci e aggiungi il seguente codice:
    <!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>

Spiegazione del codice

  1. Alla pagina viene aggiunto un DIV vuoto con l'ID gpay-container. Questo elemento DOM sarà l'elemento principale in cui viene aggiunto il pulsante Google Pay. Puoi posizionare questo elemento nel layout del tuo sito web, se opportuno.
  2. Il tag script main.js viene inserito nel DOM dopo l'elemento gpay-container. Ciò è necessario per garantire che il DIV del contenitore sia presente nel DOM prima che main.js lo interroghi. Inoltre, lo script è sincrono per garantire che venga caricato prima di pay.js, poiché il metodo onGooglePayLoaded() deve esistere prima del completamento del caricamento. Esistono altri modi per ottenere lo stesso effetto, ma non verranno discussi qui.
  3. Infine, pay.js viene caricato in modo asincrono e configura onGooglePayLoaded() come gestore di onload. Questo metodo verrà definito in main.js.

3. Configurare Google Pay

Una richiesta di pagamento Google Pay richiede un oggetto richiesta. L'oggetto definito qui come baseGooglePayRequest contiene le impostazioni comuni minime per tutte le richieste. A seconda della richiesta effettuata, verranno aggiunte impostazioni aggiuntive che esamineremo in questo codelab.

Aggiungi le costanti di configurazione di Google Pay al file main.js vuoto:

//=============================================================================
// 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);

Spiegazione del codice

  1. Imposta la variabile costante GPAY_BUTTON_CONTAINER_ID sull'ID dell'elemento DOM utilizzato nella pagina HTML come contenitore principale per il pulsante Google Pay.
  2. Crea l'oggetto di configurazione baseGooglePayRequest con le impostazioni pertinenti per la tua applicazione. Puoi trovare ogni proprietà e valore nella documentazione di riferimento. I valori mostrati in questo esempio potrebbero corrispondere o meno perfettamente alle tue esigenze, quindi esaminali attentamente.
  3. Aggiorna le proprietà merchantId e merchantName con i tuoi valori. Questi campi sono facoltativi quando l'ambiente è TEST.

Risorse

4. Aggiungi client pagamenti

Un client di pagamenti viene utilizzato per effettuare richieste di pagamento e registrare callback. In questo codelab effettueremo solo richieste di pagamento. Inoltre, puoi configurare PaymentDataCallbacks per gestire i casi in cui i dati di pagamento o l'autorizzazione sono stati modificati. Tuttavia, questi argomenti avanzati non sono trattati in questo codelab.

Aggiungi questo codice client in fondo a 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;
}

Spiegazione del codice

  1. La variabile paymentsClient conterrà l'istanza del client una volta creata. La variabile non viene accessibile direttamente dal nostro codice, ma sempre tramite il metodo getGooglePaymentsClient().
  2. Il metodo getGooglePaymentsClient() controlla se un client è già stato istanziato e restituisce l'istanza. Se non ne è stato creato uno in precedenza, ne viene creato, salvato e restituito uno. Questo metodo garantisce che venga creata e utilizzata una sola istanza per tutta la durata di questo script.
  3. Per creare un'istanza di un client, viene richiamato il metodo PaymentsClient(). In questo esempio, comunichiamo al cliente che ci troviamo in un ambiente TEST. L'alternativa è PRODUCTION. Tuttavia, TEST è il valore predefinito e può essere omesso.

5. Aggiungere assistenti

Le seguenti funzioni di assistenza vengono utilizzate più avanti nello script e sono state aggiunte al solo scopo di migliorare la leggibilità e la manutenibilità del codice.

Aggiungi le funzioni helper alla fine di 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);
}

Spiegazione del codice

  1. deepCopy() è un'utilità che utilizza la serializzazione e la deserializzazione JSON per creare una copia completa dell'oggetto fornito. È un modo pratico per clonare gli oggetti senza preoccuparsi dei riferimenti condivisi.
  2. renderGooglePayButton() è un'utilità che richiama il metodo della libreria createButton() per visualizzare il pulsante Google Pay. L'argomento passato è un insieme di opzioni che definiscono il comportamento del pulsante, ad esempio la registrazione della funzione onGooglePaymentButtonClicked() per gestire i clic sul pulsante.

6. Aggiungere gestori di eventi

In questo script configuriamo due gestori di eventi. La prima viene chiamata quando il caricamento della libreria pay.js è terminato, mentre la seconda viene chiamata quando viene fatto clic sul pulsante Google Pay.

Aggiungi i gestori di eventi alla fine di 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);
}

Spiegazione del codice

  1. onGooglePayLoaded() viene richiamato al termine del caricamento dello script pay.js, come definito nel file HTML. Viene richiamato il metodo isReadyToPay() per determinare se mostrare o meno il pulsante Google Pay. Se il consumatore è pronto a pagare (ovvero ha aggiunto un metodo di pagamento a Google Wallet), viene visualizzato il pulsante Google Pay.
  2. onGooglePaymentButtonClicked() viene richiamato quando viene fatto clic sul pulsante Google Pay. Questo metodo richiama il metodo della libreria loadPaymentData(), che viene utilizzato per recuperare un token di pagamento. Una volta ottenuto il token di pagamento, invialo al gateway di pagamento per l'elaborazione della transazione. transactionInfo descrive la transazione che deve essere elaborata con questo clic del pulsante.

7. Conclusione

Congratulazioni per aver completato questo codelab. Hai imparato a integrare l'API Google Pay in un sito web.

Esegui il progetto

Testare con Google Chrome

Utilizzando il browser web Google Chrome, apri index.html utilizzando File > Apri file… dal menu principale di Chrome. Chrome eseguirà main.js quando il progetto viene aperto in questo modo. Altri browser web potrebbero non consentire l'esecuzione di JavaScript.

– o –

Test con un server web locale

Se hai installato Python, esegui python3 -m http.server da un prompt del terminale nella cartella principale pay-web-101.

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

Poi, visita il tuo sito all'indirizzo http://localhost:8000.

Come procedere

Risorse aggiuntive