Notificaciones de gestión del ciclo de vida de los tokens

Información general

Las futuras notificaciones de gestión del ciclo de vida (LCM) de los tokens se envían desde la API Google Pay Online a la tokenUpdateUrl proporcionada en el momento de la transacción original. Se envían si un token se desactiva o se elimina. También se envían en la medida de lo posible con reintentos en caso de que no se entreguen. A continuación, se muestra un ejemplo del flujo del ciclo de vida de una tarjeta cuando un usuario la elimina de Google Wallet:

MerchantTokenUpdateNotificationRequest

Un mensaje HTTP POST de la API Google Pay Online incluye un cuerpo JSON que encapsula una carga útil cifrada. La carga útil se cifra con tu clave de cifrado pública compartida y se firma con la clave privada de Google. Puedes descifrar con tu clave de cifrado privada y verificar con la clave de firma raíz de Google. Este formato de envoltorio de carga útil cifrada es idéntico al que puedes recibir como PaymentMethodToken. Puedes usar la misma biblioteca para descifrar esta notificación de LCM. Dentro de la carga útil cifrada, hay un objeto MerchantTokenUpdateNotificationRequest, como se detalla aquí.

Propiedad	Tipo	Necesidad	Descripción
messageId	string	Obligatorio	ID único de esta notificación para eliminar duplicados de mensajes y con fines de depuración. Si esta notificación no se envía correctamente, seguirá siendo la misma en futuros reintentos.
targetNotificationUrl	string	Obligatorio	La URL de destino de esta notificación. Debe confirmar que esta URL es el endpoint que quiere usar para recibir notificaciones de gestión del ciclo de vida 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	Marca de tiempo de cuándo se creó originalmente esta notificación. Se mantiene igual en los reintentos posteriores. Si recibe varias notificaciones para el mismo ID de token, solo se considerará precisa la notificación con la marca de tiempo más reciente.
apiVersion	int	Obligatorio	Versión principal de la API.
apiVersionMinor	int	Obligatorio	Versión secundaria de la API.
merchantTokenId	Cadena	Obligatorio	El ID de token de comerciante con una actualización. Es el ID que se devolvió originalmente cuando el usuario completó el flujo de Google Pay para el MIT. Este es un campo de la carga útil cifrada que se envía en el objeto Card.
cardUpdateInfo	CardUpdateInfo	Obligatorio	Contiene actualizaciones del token.

CardUpdateInfo

Propiedad	Tipo	Necesidad	Descripción
fpanSuffix	string	Condicional	Una descripción que ayuda a los usuarios a identificar el número de cuenta principal (FPAN) subyacente. Es una cadena de cuatro dígitos que contiene los cuatro últimos caracteres del FPAN. Cuando está presente, se puede suponer que el estado del token está activo. No se incluye si no hay cambios.
tokenState	cadena(enum)	Condicional	El nuevo estado del token, si ha cambiado desde la transacción inicial o la notificación anterior. No se incluye 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 ha recibido correctamente. Se puede proporcionar información adicional sobre el estado en el cuerpo de la respuesta como un objeto JSON, tal como se describe en la siguiente tabla.
401	El valor targetNotificationUrl de MerchantTokenUpdateNotificationRequest no es válido. Se pueden inhabilitar todas las notificaciones futuras de este token.
5xx	Error temporal del servidor. La notificación se debe enviar de nuevo 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	ID del mensaje generado a partir de la solicitud. Debe coincidir con el ID del mensaje de la solicitud. De lo contrario, la respuesta se puede ignorar y se detendrán las notificaciones futuras de este token.
status	cadena(enum)	Obligatorio	El comerciante o el proveedor de servicios de pago pueden devolver un estado que refleje la ingestión de la notificación y el uso del token. Los valores válidos son estos: SUCCESS TOKEN_NOT_IN_USE TOKEN_NOT_FOUND

Ejemplo

Notificación de ciclo de vida

Solicitud de notificación

Se trata de la solicitud HTTP POST que contiene la notificación del ciclo de vida del token, enviada desde Google Pay a tu endpoint. El cuerpo es una carga útil cifrada.

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\"}"
  }

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

Respuesta de notificación

  HTTP 200 OK
  Content-Type: application/json

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

Hacer pruebas con el endpoint tokenUpdateUrl

En el modo PRUEBA, Google Pay envía una notificación de LCM de token a tu tokenUpdateUrl. Para activarlo, sigue estos pasos:

• Completa una transacción de prueba llamando a loadPaymentData con un objeto *TransactionInfo y rellenando el campo tokenUpdateUrl con la URL de tu endpoint.
  Nota: Para completar la transacción y activar la notificación en el modo PRUEBA, debes hacer clic en el botón Continuar o Pagar de la hoja de pago.
• El servicio de Google enviará una notificación de LCM de token a tu endpoint.
• Verifica que puedes descifrar la notificación con tu clave privada. Ten en cuenta que, en el modo PRUEBA, esta notificación siempre cambiará los últimos cuatro dígitos del número de tarjeta a "1234" y contendrá "tokenState": "DISABLED", independientemente del token de la solicitud.