Usar callbacks

Este guia explica como usar callbacks com a API Google Pay for Passes. Para cada valor salvo e excluído, o Google faz o callback dos parceiros em um endpoint HTTPs no nível da classe pré-configurado com dados sobre a gravação/exclusão do usuário com uma assinatura.

Pré-requisitos

Antes de dar os primeiros passos, revise os seguintes pré-requisitos:

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

Implementar callbacks

Para cada gravação ou exclusão realizada pelo usuário em um objeto, o Google faz callbacks para os comerciantes com detalhes sobre a gravação ou a exclusão em um URL por classe. Os comerciantes precisam verificar inicialmente a autenticidade da mensagem usando as chaves públicas. Assim que puderem verificar a mensagem, os callbacks poderão ser usados em operações downstream.

Verificar a assinatura

Recomendamos usar 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 implementar PaymentMethodTokenRecipient usando a biblioteca do Tink:

private static final String PUBLIC_KEY_URL = "https://pay.google.com/gp/m/issuer/keys". // Public key URL provided by Google.
private static final String SENDER_ID = "GooglePayPasses". // Constant.

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

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());
      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) {
       // …
    }
}

Formato de mensagem esperado

O formato da mensagem é JSON serializado em uma string e contém as seguintes propriedades:

Identificador Descrição
classId

Código de classe totalmente qualificado. Usa o seguinte formato:


<issuer_id.class_id>
objectId

Código de objeto totalmente qualificado. Usa o seguinte formato:


<issuer_id.object_id>
expTimeMillis Tempo de expiração em milissegundos desde EPOCH. Depois do horário de expiração, a mensagem será considerada inválida.
eventType Pode ser "del" ou "save" para DELETE e SAVE.
nonce Nonce para rastrear as exibições 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: Google-Valuables
  • Content-Type: application/json

Configure o servidor corretamente. Dessa maneira, ele não rejeita a solicitação. Por exemplo, convém definir o seguinte em robots.txt:

User-agent: Google-Valuables
Disallow:

Novas tentativas

Os callbacks são feitos na medida do possível. O Google tenta entregar a mensagem por três dias em caso de falhas temporárias. Depois de três dias, a mensagem será descartada e não será tentada novamente no futuro.

Entregas duplicadas

Talvez haja entregas duplicadas em alguns casos. Recomendamos usar nonce para excluí-las.