Esta página foi traduzida pela API Cloud Translation.

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 da Web Google Chrome ou outra maneira de testar um site local.
Para a produção, você vai precisar de uma merchantId do Google Pay. O registro no Console do Google Pay e da Carteira leva apenas um minuto.

Acompanhe o processo usando o Project IDX

2. Criar a página HTML

Criar arquivos de projeto

Crie uma pasta no computador com o nome gpay-web-101 e, dentro dela, crie dois arquivos de texto vazios com os nomes index.html e main.js.A estrutura do diretório deve ficar assim:
```
gpay-web-101/
  index.html
  main.js
```

Abra index.html no ambiente de desenvolvimento integrado de sua preferência 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>

Explicação do código

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. Você pode posicionar esse elemento no layout do seu site, quando apropriado.
A tag de script main.js é colocada no DOM após o elemento gpay-container. Isso é necessário para garantir que o DIV do contêiner esteja presente no DOM antes que as consultas main.js o solicitem. 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.
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 requer um objeto de solicitação. O objeto definido aqui como baseGooglePayRequest contém as configurações mínimas comuns 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);

Explicação do código

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

Recursos

Postagem do blog: Quer facilitar a finalização da compra com o Google Pay? Configure suas opções de pagamento.
Referência da API: documentação dos objetos de solicitação da API Google Pay
Referência da API: consulte PaymentMethod para mais informações sobre os métodos de autorização permitidos, as redes de cartão permitidas e as especificações de tokenização, incluindo o valor de gateway adequado.

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 PaymentDataCallbacks para processar quando os dados de pagamento ou a autorização mudarem. No entanto, esses tópicos avançados não são abordados neste codelab.

Anexe este código do 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;
}

Explicação do código

A variável paymentsClient vai manter a instância para o cliente depois que ela for criada. A variável não é acessada diretamente pelo nosso código, mas sempre pelo método getGooglePaymentsClient().
O método getGooglePaymentsClient() verifica se um cliente já foi instanciado e retorna essa instância. Se nenhuma instância foi instanciada anteriormente, uma será criada, salva e retornada. Esse método garante que apenas uma instância seja criada e usada durante a vida útil do script.
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 funções auxiliares a seguir são usadas mais adiante no script e foram adicionadas com o único objetivo de melhorar a legibilidade e a manutenção do código.

Anexe 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);
}

Explicação do código

deepCopy() é um utilitário que usa a serialização e desserialização JSON para criar uma cópia profunda do objeto fornecido. É uma maneira conveniente de clonar objetos sem se preocupar com referências compartilhadas.
renderGooglePayButton() é um utilitário 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 no botão.

6. Adicionar manipuladores de eventos

Neste script, estamos configurando dois gerenciadores de eventos. O primeiro é chamado quando a biblioteca pay.js termina de carregar, e o outro é chamado 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);
}

Explicação do código

onGooglePayLoaded() é invocado quando o carregamento do script pay.js é concluído, conforme definido no arquivo HTML. O método isReadyToPay() é invocado para determinar se o botão do Google Pay vai ser mostrado ou não. Se o consumidor estiver pronto para pagar (ou seja, tiver adicionado uma forma de pagamento à Carteira do Google), o botão do Google Pay será renderizado.
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 precisa ser processada com esse clique no 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 File > Open File... 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 do JavaScript.

– ou –

Testar com um servidor da Web local

Se você tiver o Python instalado, execute python3 -m http.server em um prompt de terminal na pasta 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

Participe da conversa no canal#payments do Discord
Siga @GooglePayDevs no X
Assistir vídeos relacionados ao Google Pay no YouTube