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 com base no melhor esforço com novas tentativas para entregas com falha. Confira 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 contém um corpo JSON que encapsula um payload criptografado. O payload é criptografado com sua chave de criptografia pública compartilhada e assinado pela chave privada do Google's. Você pode 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 o PaymentMethodToken. Você pode usar a mesma biblioteca para descriptografar essa notificação de LCM. No payload criptografado, há um objeto MerchantTokenUpdateNotificationRequest conforme detalhado aqui.

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

ID exclusivo dessa notificação para remover a duplicação das mensagens e para fins de depuração.

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

O URL pretendido para essa notificação. Confirme se esse 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 essa 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. Esse é 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 Card objeto.
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, na sigla em inglês) subjacente. É uma string de quatro dígitos que contém os quatro últimos caracteres do FPAN.

Quando presente, o estado do token pode ser considerado ativo.

Ele não está presente se não houver mudança.
tokenState string(enum) Condicional

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

Ele não está presente se não houver mudança.

O valor válido é DISABLED.

MerchantTokenUpdateNotificationResponse

Códigos de resposta HTTP

Código de resposta HTTP Uso
200 A notificação foi recebida. Informações de status adicionais podem ser fornecidas no corpo da resposta como um objeto JSON, conforme descrito na próxima tabela.
401 O targetNotificationUrl no 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 pela 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

Essa é a solicitação HTTP POST que contém a notificação de 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\"}"
  }

MerchantTokenUpdateNotificationRequest descriptografado

  {  // 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",
  }

Teste com o endpoint tokenUpdateUrl

No modo de 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 *TransactionInfo objeto, preenchendo o tokenUpdateUrl campo com o URL do endpoint.
  • O serviço do Google vai enviar uma notificação de LCM de token para seu endpoint.
  • Verifique se você pode descriptografar a notificação usando sua chave privada. No modo de TESTE, essa notificação sempre vai mudar os quatro últimos dígitos do número do cartão para "1234" e conter "tokenState": "DISABLED", independentemente do token na solicitação.