Notifications de gestion du cycle de vie des jetons

Présentation

Les futures notifications de gestion du cycle de vie des jetons sont envoyées par 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 avec des nouvelles tentatives en cas d'échec de la livraison. Voici un exemple de flux de gestion du cycle de vie lorsqu'un utilisateur supprime une carte de Google Wallet :

MerchantTokenUpdateNotificationRequest

Un message HTTP POST 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's. Vous pouvez déchiffrer avec votre clé de chiffrement privée et vérifier avec la clé de signature racine de Google. Ce format de wrapper 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 de gestion du cycle de vie. Dans la charge utile chiffrée, vous trouverez un objet MerchantTokenUpdateNotificationRequest comme décrit ici.

Propriété	Type	Nécessité	Description
messageId	chaîne	Obligatoire	ID unique de cette notification pour dédupliquer les messages et à des fins de débogage. Si cette notification n'est pas remise, 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 de gestion du cycle de vie des jetons 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 initiale 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 la notification avec l'horodatage le plus récent 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 de jeton marchand avec une mise à jour. Il s'agit de l'ID renvoyé initialement lorsque l'utilisateur a terminé le flux Google Pay pour le marchand initié par le marchand. Il s'agit d'un champ de la charge utile chiffrée, envoyé dans l'objet Card objet.
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 sous-jacent. Il s'agit d'une chaîne de quatre chiffres contenant les quatre derniers caractères du numéro de compte principal de financement. Lorsqu'il est présent, l'état du jeton peut être considéré comme actif. Il n'est pas présent en l'absence de modification.
tokenState	chaîne(enum)	Conditionnel	Nouvel état du jeton, s'il a changé depuis la transaction initiale ou la notification précédente. Il n'est pas présent en l'absence de modification. La valeur valide est DISABLED.

MerchantTokenUpdateNotificationResponse

Codes de réponse HTTP

Code de réponse HTTP	Utilisation
200	La notification a bien été reçue. Des informations d'état supplémentaires 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 le MerchantTokenUpdateNotificationRequest n'est pas valide. Toutes les futures notifications pour ce jeton peuvent être désactivées.
5xx	Erreur de serveur temporaire. 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 de message généré à partir de la requête. Il doit correspondre à l'ID de 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	chaîne(enum)	Obligatoire	Le marchand ou le fournisseur de services de paiement peut renvoyer un état qui reflète son ingestion de la notification et son utilisation du jeton. Les valeurs valides sont les suivantes : SUCCESS TOKEN_NOT_IN_USE TOKEN_NOT_FOUND

Exemple

Notification de gestion du cycle de vie

Demande de notification

Il s'agit de la requête HTTP POST contenant la notification de gestion du cycle de vie 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\"}"
  }

MerchantTokenUpdateNotificationRequest déchiffré

  {  // 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 de gestion du cycle de vie du jeton à votre adresse tokenUpdateUrl. Pour déclencher cette action, procédez comme suit :

• Effectuez une transaction test en appelant loadPaymentData avec un *TransactionInfo objet, en renseignant le tokenUpdateUrl champ avec l'URL de votre point de terminaison.
  Remarque : Pour effectuer la transaction et déclencher la notification en mode TEST, vous devez cliquer sur le bouton Continuer ou Payer dans la feuille de paiement.
• Le service de Google envoie une notification de gestion du cycle de vie du 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 remplace toujours les quatre derniers chiffres du numéro de carte par "1234" et contient "tokenState": "DISABLED", quel que soit le jeton de la requête.