Conceptos básicos de la API de Google Pay para la Web

1. Introducción

Qué compilarás

Cuando completes este codelab, tendrás un sitio web viable mínimo con una integración de Google Pay que funcione. Este proyecto recupera un token de pago que se puede enviar a un proveedor de servicios de pagos para su procesamiento.

Qué aprenderás

Cómo cargar y configurar la API de Google Pay
Cómo mostrar el botón de Google Pay y controlar los clics
Cómo solicitar un token de pago de Google Pay

Requisitos

Un editor de texto de tu elección para editar archivos HTML y JavaScript
El navegador web Google Chrome o alguna otra forma de probar un sitio web local
Para la producción, necesitarás un merchantId de Google Pay. Solo te llevará un minuto registrarte en la Consola de Google Pay y la Billetera, así que puedes hacerlo ahora.

Sigue los pasos con Firebase Studio

2. Crea la página HTML

Crea archivos del proyecto

Crea una carpeta en tu computadora llamada gpay-web-101 y, dentro de ella, crea dos archivos de texto vacíos llamados index.html y main.js.La estructura de tu directorio debería verse de la siguiente manera:
```
gpay-web-101/
  index.html
  main.js
```

Abre index.html en el IDE que prefieras y agrega el siguiente código:

<!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>

Explicación del código

Se agrega un elemento DIV vacío a la página con el ID gpay-container. Este elemento DOM será el elemento principal en el que se agregará el botón de Google Pay. Puedes colocar este elemento en el diseño de tu sitio web donde sea apropiado.
La etiqueta de secuencia de comandos main.js se coloca en el DOM después del elemento gpay-container. Esto es necesario para garantizar que el DIV del contenedor esté presente en el DOM antes de que main.js lo consulte. Además, la secuencia de comandos es síncrona para garantizar que se cargue antes de que se cargue pay.js, ya que el método onGooglePayLoaded() debe existir antes de que se complete la carga. Existen otras formas de lograr el mismo efecto, pero no se analizarán aquí.
Por último, pay.js se carga de forma asíncrona y configura onGooglePayLoaded() como su controlador onload. Este método se definirá en main.js.

3. Configura Google Pay

Una solicitud de pago de Google Pay requiere un objeto de solicitud. El objeto definido aquí como baseGooglePayRequest contiene la configuración común mínima para todas las solicitudes. Se agregarán parámetros de configuración adicionales según la solicitud realizada, que revisaremos en este codelab.

Agrega las constantes de configuración de Google Pay al archivo main.js vacío:

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

Explicación del código

Establece la variable constante GPAY_BUTTON_CONTAINER_ID en el ID del elemento DOM que se usa en la página HTML como contenedor principal del botón de Google Pay.
Crea el objeto de configuración baseGooglePayRequest con la configuración pertinente para tu aplicación. Cada una de las propiedades y los valores se pueden encontrar en la documentación de referencia. Los valores que se muestran en este ejemplo pueden coincidir o no perfectamente con tus necesidades, por lo que debes revisarlos con atención.
Actualiza las propiedades merchantId y merchantName con tus propios valores. Estos campos son opcionales cuando el entorno es TEST.

Recursos

Entrada de blog: ¿Quieres un proceso de confirmación de compra más fluido con Google Pay? ¡Configura tus opciones de pago!
Referencia de la API: Documentación de los objetos de solicitud de la API de Google Pay
Referencia de la API: Consulta PaymentMethod para obtener más información sobre los métodos de autorización y las redes de tarjetas permitidos, y las especificaciones de tokenización, incluido el valor de puerta de enlace adecuado.

4. Agrega un cliente de pagos

Se usa un cliente de pagos para realizar solicitudes de pago y registrar devoluciones de llamada. En este codelab, solo realizaremos solicitudes de pago. Además, puedes configurar PaymentDataCallbacks para que controle los casos en los que cambiaron los datos de pago o la autorización. Sin embargo, estos temas avanzados no se abordan en este codelab.

Agrega este código del cliente al final 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;
}

Explicación del código

La variable paymentsClient contendrá la instancia del cliente una vez que se haya creado. Nuestros códigos no acceden a la variable directamente, sino que siempre lo hacen a través del método getGooglePaymentsClient().
El método getGooglePaymentsClient() verifica si ya se creó una instancia de un cliente y devuelve esa instancia. Si no se creó una instancia previamente, se crea, guarda y devuelve una. Este método garantiza que solo se cree y se use una instancia durante la vida útil de esta secuencia de comandos.
Para crear una instancia de un cliente, se invoca el método PaymentsClient(). En este ejemplo, le indicamos al cliente que estamos en un entorno TEST. La alternativa es PRODUCTION. Sin embargo, TEST es el valor predeterminado y se puede omitir.

5. Cómo agregar ayudantes

Las siguientes funciones auxiliares se usan más adelante en la secuencia de comandos y se agregaron con el único propósito de mejorar la legibilidad y el mantenimiento del código.

Agrega las funciones auxiliares al final 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);
}

Explicación del código

deepCopy() es una utilidad que usa la serialización y deserialización de JSON para crear una copia profunda del objeto proporcionado. Es una forma conveniente de clonar objetos sin preocuparse por las referencias compartidas.
renderGooglePayButton() es una utilidad que invoca el método de la biblioteca createButton() para mostrar el botón de Google Pay. El argumento que se pasa es un conjunto de opciones que definen cómo debe comportarse el botón, como registrar la función onGooglePaymentButtonClicked() para controlar los clics en el botón.

6. Cómo agregar controladores de eventos

En este script, configuramos dos controladores de eventos. La primera se llama cuando finaliza la carga de la biblioteca pay.js y la otra se llama cuando se hace clic en el botón de Google Pay.

Agrega los controladores de eventos a la parte inferior 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);
}

Explicación del código

Se invoca onGooglePayLoaded() cuando se completa la carga de la secuencia de comandos pay.js, como se define en el archivo HTML. Se invoca el método isReadyToPay() para determinar si se debe mostrar el botón de Google Pay. Si el consumidor está listo para pagar (es decir, agregó una forma de pago a su Billetera de Google), se renderizará el botón de Google Pay.
Se invoca onGooglePaymentButtonClicked() cuando se hace clic en el botón de Google Pay. Este método invoca el método de biblioteca loadPaymentData() que se usa para recuperar un token de pago. Una vez que tengas el token de pago, lo enviarás a tu pasarela de pagos para procesar la transacción. transactionInfo describe la transacción que se debe procesar con este clic en el botón.

7. Conclusión

¡Felicitaciones por completar este codelab! Aprendiste a integrar la API de Google Pay en un sitio web.

Cómo ejecutar el proyecto

Prueba con Google Chrome

Con el navegador web Google Chrome, abre index.html con Archivo > Abrir archivo… en el menú principal de Chrome. Chrome ejecutará main.js cuando se abra el proyecto de esta manera. Es posible que otros navegadores web no permitan la ejecución de JavaScript.

– o –

Cómo realizar pruebas con un servidor web local

Si tienes instalado Python, ejecuta python3 -m http.server desde un símbolo del sistema de la terminal en la carpeta raíz pay-web-101.

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

Luego, visita tu sitio en http://localhost:8000.

Lo que vendrá

Google for Web 201: Advanced (Google para la Web 201: Avanzado)
Personaliza el botón de Google Pay
Revisa la lista de tareas de integración

Recursos adicionales

Únete a la conversación en el canal#payments en Discord
Sigue a @GooglePayDevs en X
Mira videos relacionados con Google Pay en YouTube