Adicionar e excluir callbacks

Neste guia, explicamos como usar callbacks com a API Google Wallet. Quando um cartão é criado ou excluído, o Google pode realizar um callback para o endpoint HTTPS que você escolher. Esse callback é específico do cartão e inclui dados sobre o evento, como o externalPassId e o tipo de evento. Isso pode ser usado para acompanhar o número de adições e exclusões de usuários que ocorrem. Por exemplo, os callbacks podem ser configurados para enviar eventos a um aplicativo de análise para rastrear o engajamento do cliente durante eventos promocionais.

Pré-requisitos

Antes de começar, veja os seguintes pré-requisitos:

• Destaque um endpoint HTTPS que processe solicitações POST. Esse endpoint precisa estar disponível publicamente.
• Atualize de maneira programática o URL do endpoint do callback para o emissor. Consulte a propriedade callbackOptions do emissor na API REST.
• Recomendado: use a biblioteca do Tink para verificar as assinaturas.

Implementar callbacks

Para cada adição ou exclusão realizada pelo usuário em um cartão, o Google faz callbacks para os comerciantes com detalhes sobre a inclusão ou a exclusão em um URL de callback do emissor. Os comerciantes precisam usar as chaves públicas para verificar a autenticidade da mensagem. Depois de verificar a mensagem, será possível usar callbacks para operações downstream.

Verificar a assinatura

Recomendamos que você use a biblioteca do Tink para verificar a assinatura da mensagem ao implementar o endpoint HTTPS. A biblioteca do Tink fornece o PaymentMethodTokenRecipient, um utilitário que verifica automaticamente a assinatura e retorna a mensagem real após a verificação.

O exemplo a seguir mostra como usar a biblioteca do Tink para implementar o PaymentMethodTokenRecipient:

import java.io.IOException;
import javax.servlet.http.*;
import com.google.common.io.CharStreams;
import com.google.crypto.tink.apps.paymentmethodtoken.*;

// Replace ISSUER_ID with your issuer id
private static final String RECIPIENT_ID = "ISSUER_ID";

private static final String PUBLIC_KEY_URL = "https://pay.google.com/gp/m/issuer/keys";
private static final String SENDER_ID = "GooglePayPasses";
private static final String PROTOCOL = "ECv2SigningOnly";

private static final GooglePaymentsPublicKeysManager keysManager = new GooglePaymentsPublicKeysManager.Builder()
        .setKeysUrl(PUBLIC_KEY_URL)
        .build();

public void doPost(HttpServletRequest request, HttpServletResponse response) throws IOException {
  try {
    // Extract signed message with signature from POST request body.
    String signedMessage = CharStreams.toString(request.getReader());
    PaymentMethodTokenRecipient recipient =
            new PaymentMethodTokenRecipient.Builder()
                    .protocolVersion(PROTOCOL)
                    .fetchSenderVerifyingKeysWith(keysManager)
                    .senderId(SENDER_ID)
                    .recipientId(RECIPIENT_ID)
                    .build();

    String serializedJsonMessage = recipient.unseal(signedMessage);

    // Use serializedJsonMessage to extract the details
  } catch (Exception e) {
    // Handle the error
  }
}

Formato de mensagem esperado

O formato da mensagem é JSON serializado em uma string com as seguintes propriedades:

Identificador	Descrição
externalPassId	ID de cartão externo totalmente qualificado. Usa o seguinte formato: <issuer_id.external_pass_id>
expTimeMillis	Tempo de expiração em milissegundos desde época. Depois do tempo de expiração, a mensagem precisa ser considerada inválida.
eventType	Pode ser del ou save para DELETE e SAVE.
nonce	Valor de uso único para rastrear as entregas duplicadas.

Processar a solicitação de um servidor do Google

Esta é uma lista dos campos-chave no cabeçalho da solicitação enviada para o endpoint de callback:

• User agent: Googlebot
• Tipo de conteúdo: application/json

Configure o servidor para que ele não rejeite a solicitação. Para isso, defina o seguinte em robots.txt:

User-agent: Googlebot
Disallow:

Novas tentativas

Os callbacks são feitos na medida do possível. O Google tenta duas vezes explicar falhas temporárias. Depois de tentar duas vezes, o Google exclui a mensagem e não tenta fazer outros envios.

Entregas duplicadas

Pode haver entregas duplicadas em alguns casos. Use nonce para eliminar as duplicações.