Notificações de gerenciamento do ciclo de vida do token

Visão geral

As futuras notificações de gerenciamento do ciclo de vida (LCM, na sigla em inglês) do token são enviadas da API Google Pay Online para o tokenUpdateUrl fornecido no momento da transação original. Elas são enviadas se um token for desativado ou excluído. Elas também são enviadas na medida do possível com novas tentativas para entregas com falha. Este é um exemplo de fluxo de LCM quando um cartão é removido da Carteira do Google por um usuário:

MerchantTokenUpdateNotificationRequest

Uma mensagem HTTP POST da API Google Pay Online, que carrega um corpo JSON encapsulando um payload criptografado. O payload é criptografado com sua chave de criptografia pública compartilhada e assinado pela chave privada do Google. É possível descriptografar com sua chave de criptografia privada e verificar com a chave de assinatura raiz do Google. Esse formato de wrapper de payload criptografado é idêntico ao que você pode receber como PaymentMethodToken. Você pode usar a mesma biblioteca para descriptografar essa notificação do LCM. Dentro do payload criptografado, há um objeto MerchantTokenUpdateNotificationRequest, conforme detalhado aqui.

Propriedade Tipo Necessidade Descrição
messageId string Obrigatório

ID exclusivo desta notificação para remover mensagens duplicadas e para fins de depuração.

Se essa notificação não for entregue, ela vai permanecer a mesma para novas tentativas.
targetNotificationUrl string Obrigatório

O URL pretendido para esta notificação. Confirme se este URL é o endpoint pretendido para receber notificações de LCM de token do Google Pay.
timestamp string Obrigatório

Carimbo de data/hora em que esta notificação foi criada originalmente. Ele permanece o mesmo para novas tentativas.

Se você receber várias notificações para o mesmo ID de token, apenas a notificação com o carimbo de data/hora mais recente será considerada precisa.
apiVersion int Obrigatório Versão principal da API.
apiVersionMinor int Obrigatório Versão secundária da API.
merchantTokenId String Obrigatório O ID do token do comerciante com uma atualização. É o ID retornado originalmente quando o usuário concluiu o fluxo do Google Pay para o MIT. Esse é um campo no payload criptografado, enviado no objeto Objeto Card.
cardUpdateInfo CardUpdateInfo Obrigatório Contém atualizações para o token.

CardUpdateInfo

Propriedade Tipo Necessidade Descrição
fpanSuffix string Condicional

Uma descrição para ajudar os usuários a identificar o número da conta principal de financiamento (FPAN) associado. É uma string de quatro dígitos que contém os quatro últimos caracteres do FPAN.

Quando ele está presente, presume-se que o estado do token esteja ativo.

Ele não aparece se não houver mudanças.
tokenState string(enum) Condicional

O novo estado do token, se ele tiver sido alterado desde a transação inicial ou a notificação anterior.

Ele não aparece se não houver mudanças.

O valor válido é de DISABLED.

MerchantTokenUpdateNotificationResponse

Códigos de resposta HTTP

Código de resposta HTTP Uso
200 A notificação foi recebida. Outras informações de status podem ser fornecidas no corpo da resposta como um objeto JSON, conforme descrito na próxima tabela.
401 O targetNotificationUrl em MerchantTokenUpdateNotificationRequest é inválido. Todas as notificações futuras para esse token podem ser desativadas.
5xx Erro de servidor temporário. A notificação precisa ser enviada novamente mais tarde.
Outro Erro não repetível. A notificação não deve ser enviada novamente mais tarde.
Propriedade Tipo Necessidade Descrição
requestMessageId string Obrigatório

O ID da mensagem gerado na solicitação.

Ele precisa corresponder ao ID da mensagem da solicitação. Caso contrário, a resposta poderá ser ignorada e as notificações futuras para esse token serão interrompidas.
status string(enum) Obrigatório

O comerciante ou o provedor de serviços de pagamento (PSP) pode retornar um status que reflita a ingestão da notificação e o uso do token.

Os valores válidos são:

  • SUCCESS
  • TOKEN_NOT_IN_USE
  • TOKEN_NOT_FOUND

Exemplo

Notificação de ciclo de vida

Solicitação de notificação

Esta é a solicitação HTTP POST que contém a notificação do LCM do token, enviada do Google Pay para seu endpoint. O corpo é um payload criptografado.

Solicitação HTTP

  HTTP POST /token/notification/123
  Host: api.merchant.com
  Content-Type: application/json

  {
    "protocolVersion":"ECv2",
    "signature":"MEQCIH6Q4OwQ0jAceFEkGF0JID6sJNXxOEi4r+mA7biRxqBQAiAondqoUpU/bdsrAOpZIsrHQS9nwiiNwOrr24RyPeHA0Q\u003d\u003d",
    "intermediateSigningKey":{
      "signedKey": "{\"keyExpiration\":\"1542323393147\",\"keyValue\":\"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE/1+3HBVSbdv+j7NaArdgMyoSAM43yRydzqdg1TxodSzA96Dj4Mc1EiKroxxunavVIvdxGnJeFViTzFvzFRxyCw\\u003d\\u003d\"}",
      "signatures": ["MEYCIQCO2EIi48s8VTH+ilMEpoXLFfkxAwHjfPSCVED/QDSHmQIhALLJmrUlNAY8hDQRV/y1iKZGsWpeNmIP+z+tCQHQxP0v"]
    },
    "signedMessage":"{\"tag\":\"jpGz1F1Bcoi/fCNxI9n7Qrsw7i7KHrGtTf3NrRclt+U\\u003d\",\"ephemeralPublicKey\":\"BJatyFvFPPD21l8/uLP46Ta1hsKHndf8Z+tAgk+DEPQgYTkhHy19cF3h/bXs0tWTmZtnNm+vlVrKbRU9K8+7cZs\\u003d\",\"encryptedMessage\":\"mKOoXwi8OavZ\"}"
  }

Decrypted MerchantTokenUpdateNotificationRequest

  {  // MerchantTokenUpdateNotificationRequest
    "messageId": "ZlxoWhLC3su",
    "targetNotificationUrl":
      "https://api.merchant.com/token/notification/123",
    "timestamp": "2025-03-28T07:53:12.39Z",
    "apiVersion": 1,
    "apiVersionMinor": 0,
    "merchantTokenId": "123",
    "cardUpdateInfo": {
      "tokenState": "DISABLED"
    }
  }

Resposta de notificação

  HTTP 200 OK
  Content-Type: application/json

  {  // MerchantTokenUpdateNotificationResponse
    "requestMessageId": "ZlxoWhLC3su",
    "status": "SUCCESS",
  }

Testar com o endpoint tokenUpdateUrl

No modo TESTE, o Google Pay envia uma notificação de LCM de token para seu tokenUpdateUrl. Para acionar isso, siga estas etapas:

  • Conclua uma transação de teste chamando loadPaymentData com um objeto *TransactionInfo, preenchendo o campo tokenUpdateUrl com o URL do endpoint.
  • O serviço do Google vai enviar uma notificação de LCM de token para seu endpoint.
  • Verifique se é possível descriptografar a notificação usando sua chave privada. No modo de TESTE, essa notificação sempre muda os últimos quatro dígitos do número do cartão para "1234" e contém "tokenState": "DISABLED", independente do token na solicitação.