Introdução à API Google Pay para Web: noções básicas

1. Introdução

O que você vai criar

Ao concluir este codelab, você terá um site mínimo viável com uma integração funcional do Google Pay. Esse projeto recupera um token de pagamento que pode ser enviado a um provedor de serviços de pagamento para processamento.

O que você vai aprender

  • Como carregar e configurar a API Google Pay
  • Como mostrar o botão do Google Pay e processar cliques
  • Como solicitar um token de pagamento do Google Pay

O que é necessário

  • Um editor de texto de sua escolha para editar arquivos HTML e JavaScript.
  • O navegador Google Chrome ou outra maneira de testar um site local.
  • Para produção, você vai precisar de um merchantId do Google Pay. Leva apenas um minuto para se registrar no Console do Google Pay e da Carteira. Então, faça isso agora.

Acompanhe usando o Firebase Studio

Abrir no Firebase Studio

2. Criar a página HTML

Criar arquivos de projeto

  1. Crie uma pasta no computador chamada gpay-web-101 e, dentro dela, crie dois arquivos de texto vazios chamados index.html e main.js.A estrutura de diretórios deve ser assim:
    gpay-web-101/
  index.html
  main.js
  2. Abra index.html no ambiente de desenvolvimento integrado de sua escolha e adicione o seguinte 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>

Explicar códigos

  1. Uma DIV vazia é adicionada à página com o ID gpay-container. Esse elemento DOM será o elemento pai em que o botão do Google Pay será adicionado. Posicione esse elemento no layout do seu site onde for apropriado.
  2. A tag script main.js é colocada no DOM depois do elemento gpay-container. Isso é necessário para garantir que a DIV do contêiner esteja presente no DOM antes que o main.js faça consultas sobre ela. Além disso, o script é síncrono para garantir que ele seja carregado antes de pay.js, já que o método onGooglePayLoaded() precisa existir antes da conclusão do carregamento. Há outras maneiras de conseguir o mesmo efeito, mas elas não serão discutidas aqui.
  3. Por fim, pay.js é carregado de forma assíncrona e configura onGooglePayLoaded() como o manipulador onload. Esse método será definido em main.js.

3. Configurar o Google Pay

Uma solicitação de pagamento do Google Pay exige um objeto de solicitação. O objeto definido aqui como baseGooglePayRequest contém as configurações comuns mínimas para todas as solicitações. Outras configurações serão adicionadas dependendo da solicitação feita, que vamos analisar neste codelab.

Adicione as constantes de configuração do Google Pay ao arquivo main.js vazio:

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

Explicar códigos

  1. Defina a variável constante GPAY_BUTTON_CONTAINER_ID como o ID do elemento DOM usado na página HTML como o contêiner principal do botão do Google Pay.
  2. Crie o objeto de configuração baseGooglePayRequest com as configurações relevantes para seu aplicativo. Cada uma das propriedades e valores pode ser encontrada na documentação de referência. Os valores mostrados neste exemplo podem ou não corresponder perfeitamente às suas necessidades. Portanto, revise com cuidado.
  3. Atualize as propriedades merchantId e merchantName com seus próprios valores. Esses campos são opcionais quando o ambiente é TEST.

Recursos

4. Adicionar cliente de pagamentos

Um cliente de pagamentos é usado para fazer solicitações de pagamento e registrar callbacks. Neste codelab, vamos fazer apenas solicitações de pagamento. Além disso, você pode configurar o PaymentDataCallbacks para lidar com mudanças nos dados de pagamento ou na autorização. No entanto, esses tópicos avançados não são abordados neste codelab.

Adicione este código de cliente à parte de baixo 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;
}

Explicar códigos

  1. A variável paymentsClient vai manter a instância do cliente depois que ela for criada. A variável não é acessada diretamente pelo nosso código, mas sempre pelo método getGooglePaymentsClient().
  2. O método getGooglePaymentsClient() verifica se um cliente já foi instanciado e retorna essa instância. Se um não foi instanciado anteriormente, um será criado, salvo e retornado. Esse método garante que apenas uma instância seja criada e usada durante todo o ciclo de vida do script.
  3. Para instanciar um cliente, o método PaymentsClient() é invocado. Neste exemplo, estamos informando ao cliente que estamos em um ambiente TEST. A alternativa é PRODUCTION. No entanto, TEST é o padrão e pode ser omitido.

5. Adicionar ajudantes

As seguintes funções auxiliares são usadas mais tarde no script e foram adicionadas com o único propósito de melhorar a legibilidade e a capacidade de manutenção do código.

Adicione as funções auxiliares à parte de baixo 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);
}

Explicar códigos

  1. deepCopy() é um utilitário que usa serialização e desserialização JSON para criar uma cópia completa do objeto fornecido. É uma maneira conveniente de clonar objetos sem se preocupar com referências compartilhadas.
  2. renderGooglePayButton() é uma utilidade que invoca o método da biblioteca createButton() para mostrar o botão do Google Pay. O argumento transmitido é um conjunto de opções que definem como o botão deve se comportar, como registrar a função onGooglePaymentButtonClicked() para processar cliques.

6. Adicionar manipuladores de eventos

Neste script, estamos configurando dois manipuladores de eventos. A primeira é chamada quando a biblioteca pay.js termina de carregar, e a outra é chamada quando o botão do Google Pay é clicado.

Anexe os manipuladores de eventos à parte de baixo 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);
}

Explicar códigos

  1. onGooglePayLoaded() é invocado quando o script pay.js termina de carregar, conforme definido no arquivo HTML. O método isReadyToPay() é invocado para determinar se o botão do Google Pay vai aparecer ou não. Se o consumidor estiver pronto para pagar (ou seja, adicionou uma forma de pagamento à Carteira do Google), o botão do Google Pay será renderizado.
  2. onGooglePaymentButtonClicked() é invocado quando o botão do Google Pay é clicado. Esse método invoca o método da biblioteca loadPaymentData(), que é usado para recuperar um token de pagamento. Depois de receber o token de pagamento, envie-o ao gateway de pagamento para processar a transação. transactionInfo descreve a transação que deve ser processada com o clique nesse botão.

7. Conclusão

Parabéns por concluir este codelab. Você aprendeu a integrar a API Google Pay a um site.

Executar o projeto

Testar com o Google Chrome

Usando o navegador da Web Google Chrome, abra index.html usando Arquivo > Abrir arquivo... no menu principal do Chrome. O Chrome vai executar main.js quando o projeto for aberto dessa forma. Outros navegadores da Web podem não permitir a execução de JavaScript.

– ou –

Testar com um servidor da Web local

Se você tiver o Python instalado, execute python3 -m http.server em um terminal no diretório raiz pay-web-101.

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

Em seguida, acesse seu site em http://localhost:8000.

O que fazer depois disso

Outros recursos