Notificaciones de administración del ciclo de vida del token

Descripción general

Las notificaciones futuras de administración del ciclo de vida (LCM) de tokens se envían desde la API de Google Pay en línea a la tokenUpdateUrl proporcionada en el momento de la transacción original. Se envían si se desactiva o borra un token. También se envían según el mejor esfuerzo con reintentos para las entregas fallidas. Este es un ejemplo del flujo de LCM cuando un usuario quita una tarjeta de la Billetera de Google:

MerchantTokenUpdateNotificationRequest

Un mensaje HTTP POST de la API de Google Pay en línea contiene un cuerpo JSON que encapsula una carga útil encriptada La carga útil se encripta con tu clave de encriptación pública compartida y se firma con la clave privada de Google. Puedes desencriptar con tu clave de encriptación privada y verificar con la clave de firma raíz de Google. Este formato de wrapper de carga útil encriptada es idéntico a lo que podrías recibir como el PaymentMethodToken. Puedes usar la misma biblioteca para desencriptar esta notificación de LCM. Dentro de la carga útil encriptada, hay un objeto MerchantTokenUpdateNotificationRequest como se detalla aquí.

Propiedad	Tipo	Necesidad	Descripción
messageId	string	Obligatorio	Es el ID único de esta notificación para anular la duplicación de los mensajes y para fines de depuración. Si esta notificación no se entrega correctamente, seguirá siendo la misma para los reintentos futuros.
targetNotificationUrl	string	Obligatorio	Es la URL prevista para esta notificación. Debes confirmar que esta URL es el extremo previsto para recibir notificaciones de LCM de tokens de Google Pay. Nota: Si la URL no es de tu propiedad o es incorrecta, debes responder con un error HTTP 400.
timestamp	string	Obligatorio	Es la marca de tiempo de la creación original de esta notificación. Seguirá siendo la misma para los reintentos futuros. Si recibes varias notificaciones para el mismo ID de token, solo se considera precisa la notificación con la marca de tiempo más reciente.
apiVersion	int	Obligatorio	Es la versión principal de la API.
apiVersionMinor	int	Obligatorio	Es la versión secundaria de la API.
merchantTokenId	String	Obligatorio	Es el ID de token del comercio con una actualización. Este es el ID que se devolvió originalmente cuando el usuario completó el flujo de Google Pay para el MIT. Este es un campo dentro de la carga útil encriptada, que se envía en el Card object.
cardUpdateInfo	CardUpdateInfo	Obligatorio	Contiene actualizaciones para el token.

CardUpdateInfo

Propiedad	Tipo	Necesidad	Descripción
fpanSuffix	string	Condicional	Es una descripción para ayudar a los usuarios a identificar el número de cuenta de fondos principal (FPAN) subyacente. Es una cadena de cuatro dígitos que contiene los últimos cuatro caracteres del FPAN. Cuando está presente, se puede suponer que el estado del token está activo. No está presente si no hay cambios.
tokenState	string(enum)	Condicional	Es el nuevo estado del token, si cambió desde la transacción inicial o la notificación anterior. No está presente si no hay cambios. El valor válido es DISABLED.

MerchantTokenUpdateNotificationResponse

Códigos de respuesta HTTP

Código de respuesta HTTP	Uso
200	La notificación se recibió correctamente. Se puede proporcionar información adicional sobre el estado en el cuerpo de la respuesta como un objeto JSON, como se describe en la siguiente tabla.
401	El targetNotificationUrl en el MerchantTokenUpdateNotificationRequest no es válido. Se pueden inhabilitar todas las notificaciones futuras para este token.
5xx	Error temporal del servidor. La notificación se debe volver a enviar más tarde.
Otro	Error que no se puede reintentar. La notificación no se debe volver a enviar más tarde.

Propiedad	Tipo	Necesidad	Descripción
requestMessageId	string	Obligatorio	Es el ID de mensaje generado a partir de la solicitud. Debe coincidir con el ID de mensaje de la solicitud; de lo contrario, se puede ignorar la respuesta y se detendrán las notificaciones futuras para este token.
status	string(enum)	Obligatorio	El comercio o el proveedor de servicios de pago (PSP) pueden devolver un estado que refleje su incorporación de la notificación y su uso del token. Estos son los valores válidos: SUCCESS TOKEN_NOT_IN_USE TOKEN_NOT_FOUND

Ejemplo

Notificación del ciclo de vida

Solicitud de notificación

Esta es la solicitud HTTP POST que contiene la notificación de LCM de tokens, que se envía desde Google Pay a tu extremo. El cuerpo es una carga útil encriptada.

Solicitud 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 desencriptado

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

Respuesta de notificación

  HTTP 200 OK
  Content-Type: application/json

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

Prueba con tu extremo tokenUpdateUrl

En el modo TEST, Google Pay envía una notificación de LCM de tokens a tu tokenUpdateUrl. Para activarla, sigue estos pasos:

• Para completar una transacción de prueba, llama a loadPaymentData con un *TransactionInfo objeto, propaga el tokenUpdateUrl campo con la URL de tu extremo.
  Nota: Para completar la transacción y activar la notificación en el modo TEST, debes hacer clic en el botón Continuar o Pagar en la hoja de pagos.
• El servicio de Google enviará una notificación de LCM de tokens a tu extremo.
• Verifica que puedas desencriptar la notificación con tu clave privada. Ten en cuenta que, en el modo TEST, esta notificación siempre cambiará los últimos 4 dígitos del número de tarjeta a "1234" y contendrá "tokenState": "DISABLED", independientemente del token de la solicitud.