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 mínimo viable 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 producción, necesitarás un merchantId de Google Pay. El registro en la Consola de Google Pay y la Billetera solo demora un minuto, así que te recomendamos que lo hagas ahora.

Sigue el proceso con Project IDX

Abre este codelab en IDX

2. Crea la página HTML

Cómo crear archivos de proyecto

  1. 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 directorios debería verse así:
    gpay-web-101/
  index.html
  main.js
  2. 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

  1. Se agrega un DIV vacío a la página con el ID gpay-container. Este elemento DOM será el elemento superior en el que se agregará el botón de Google Pay. Puedes colocar este elemento en el diseño de tu sitio web cuando corresponda.
  2. 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í.
  3. 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á la configuración adicional según la solicitud que realicemos, 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

  1. 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.
  2. Crea el objeto de configuración baseGooglePayRequest con la configuración relevante para tu aplicación. Puedes encontrar cada una de las propiedades y los valores en la documentación de referencia. Los valores que se muestran en este ejemplo pueden o no coincidir perfectamente con tus necesidades, así que revísalos con cuidado.
  3. Actualiza las propiedades merchantId y merchantName con tus propios valores. Estos campos son opcionales cuando el entorno es TEST.

Recursos

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 controlar cuándo cambian los datos de pago o la autorización. Sin embargo, estos temas avanzados no se abordan en este codelab.

Agrega este código de cliente a la parte inferior 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

  1. La variable paymentsClient retendrá la instancia para el cliente una vez que se cree. Nuestro código no accede directamente a la variable, sino que siempre lo hace el método getGooglePaymentsClient().
  2. El método getGooglePaymentsClient() verifica si ya se creó una instancia de un cliente y muestra esa instancia. Si no se creó una instancia anteriormente, se crea una, se guarda y se muestra. Este método garantiza que se cree y use una sola instancia durante la vida útil de esta secuencia de comandos.
  3. 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 a la parte inferior 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

  1. 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.
  2. renderGooglePayButton() es una utilidad que invoca el método de la biblioteca createButton() para mostrar el botón de Google Pay. El argumento pasado es un conjunto de opciones que definen cómo debe comportarse el botón, como registrar la función onGooglePaymentButtonClicked() para controlar los clics del botón.

6. Cómo agregar controladores de eventos

En esta secuencia de comandos, configuraremos dos controladores de eventos. Se llama al primero cuando termina de cargarse la biblioteca pay.js y al segundo 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

  1. 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 muestra o no 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 renderiza el botón de Google Pay.
  2. onGooglePaymentButtonClicked() se invoca cuando se hace clic en el botón de Google Pay. Este método invoca el método de la biblioteca loadPaymentData(), que se usa para recuperar un token de pago. Una vez que tengas el token de pago, lo enviarás a tu puerta de enlace de pagos para que procese 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

En el navegador web Google Chrome, abre index.html con File > Open File… 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 mensaje 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á

Recursos adicionales