Notifications de gestion du cycle de vie des jetons

Présentation

Les futures notifications de gestion du cycle de vie des jetons (LCM) sont envoyées depuis l'API Google Pay Online à l'adresse tokenUpdateUrl fournie lors de la transaction d'origine. Elles sont envoyées si un jeton est désactivé ou supprimé. Elles sont également envoyées de la manière la plus optimale possible, avec des nouvelles tentatives en cas d'échec de l'envoi. Voici un exemple de flux LCM lorsqu'un utilisateur supprime une carte de Google Wallet :

MerchantTokenUpdateNotificationRequest

Un message HTTP POST provenant de l'API Google Pay Online contient un corps JSON encapsulant une charge utile chiffrée. La charge utile est chiffrée avec votre clé de chiffrement publique partagée et signée par la clé privée de Google. Vous pouvez déchiffrer les données avec votre clé de chiffrement privée et les valider avec la clé de signature racine de Google. Ce format d'encapsulation de charge utile chiffrée est identique à celui que vous pouvez recevoir en tant que PaymentMethodToken. Vous pouvez utiliser la même bibliothèque pour déchiffrer cette notification LCM. Dans la charge utile chiffrée, il existe un objet MerchantTokenUpdateNotificationRequest, comme indiqué ici.

Propriété	Type	Nécessité	Description
messageId	chaîne	Obligatoire	ID unique de cette notification permettant de dédupliquer les messages et à des fins de débogage. Si cette notification n'est pas envoyée, elle reste la même pour les futures tentatives.
targetNotificationUrl	chaîne	Obligatoire	URL prévue pour cette notification. Vous devez confirmer que cette URL est le point de terminaison prévu pour recevoir les notifications LCM de jeton de Google Pay. Remarque : Si l'URL ne vous appartient pas ou est incorrecte, vous devez répondre avec un code HTTP 400.
timestamp	chaîne	Obligatoire	Horodatage de la création de cette notification. Il reste le même pour les futures tentatives. Si vous recevez plusieurs notifications pour le même ID de jeton, seule celle avec le dernier code temporel est considérée comme exacte.
apiVersion	int	Obligatoire	Version majeure de l'API.
apiVersionMinor	int	Obligatoire	Version mineure de l'API.
merchantTokenId	Chaîne	Obligatoire	ID du jeton du marchand avec une mise à jour. Il s'agit de l'ID renvoyé à l'origine lorsque l'utilisateur a terminé le flux Google Pay pour le MIT. Il s'agit d'un champ de la charge utile chiffrée, envoyé dans l'objet Card de Objet Card.
cardUpdateInfo	CardUpdateInfo	Obligatoire	Contient les mises à jour du jeton.

CardUpdateInfo

Propriété	Type	Nécessité	Description
fpanSuffix	chaîne	Conditionnel	Description permettant aux utilisateurs d'identifier le numéro de compte principal de financement (FPAN) sous-jacent. Il s'agit d'une chaîne de quatre chiffres contenant les quatre derniers caractères du FPAN. En sa présence, l'état du jeton peut être considéré comme actif. Elle n'est pas présente si aucune modification n'a été apportée.
tokenState	string(enum)	Conditionnel	Nouvel état du jeton, s'il a changé depuis la transaction initiale ou la notification précédente. Elle n'est pas présente si aucune modification n'a été apportée. La plage de valeurs valides est DISABLED.

MerchantTokenUpdateNotificationResponse

Codes de réponse HTTP

Code de réponse HTTP	Utilisation
200	La notification a bien été reçue. Des informations supplémentaires sur l'état peuvent être fournies dans le corps de la réponse sous la forme d'un objet JSON, comme décrit dans le tableau suivant.
401	Le targetNotificationUrl dans MerchantTokenUpdateNotificationRequest n'est pas valide. Vous pouvez désactiver toutes les futures notifications pour ce jeton.
5xx	Erreur temporaire du serveur. La notification doit être renvoyée ultérieurement.
Autre	Erreur non récupérable. La notification ne doit pas être renvoyée ultérieurement.

Propriété	Type	Nécessité	Description
requestMessageId	chaîne	Obligatoire	ID du message généré à partir de la requête. Il doit correspondre à l'ID du message de la requête. Sinon, la réponse peut être ignorée et les futures notifications pour ce jeton sont arrêtées.
status	string(enum)	Obligatoire	Le marchand ou le prestataire de services de paiement (PSP) peuvent renvoyer un état qui reflète leur ingestion de la notification et leur utilisation du jeton. Les valeurs valides sont les suivantes : SUCCESS TOKEN_NOT_IN_USE TOKEN_NOT_FOUND

Exemple

Notification de cycle de vie

Demande de notification

Il s'agit de la requête HTTP POST contenant la notification LCM du jeton, envoyée par Google Pay à votre point de terminaison. Le corps est une charge utile chiffrée.

Requête 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"
    }
  }

Réponse de notification

  HTTP 200 OK
  Content-Type: application/json

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

Tester avec votre point de terminaison tokenUpdateUrl

En mode TEST, Google Pay envoie une notification LCM de jeton à votre tokenUpdateUrl. Pour déclencher cette action, procédez comme suit :

• Effectuez une transaction test en appelant loadPaymentData avec un objet *TransactionInfo, en renseignant le champ tokenUpdateUrl avec l'URL de votre point de terminaison.
  Remarque : Pour finaliser la transaction et déclencher la notification en mode TEST, vous devez cliquer sur le bouton Continuer ou Payer dans la fiche de paie.
• Le service Google enverra une notification LCM de jeton à votre point de terminaison.
• Vérifiez que vous pouvez déchiffrer la notification à l'aide de votre clé privée. Notez qu'en mode TEST, cette notification remplacera toujours les quatre derniers chiffres du numéro de carte par "1234" et contiendra "tokenState": "DISABLED", quel que soit le jeton de la demande.