Benachrichtigungen zur Verwaltung des Token-Lebenszyklus

Übersicht

Zukünftige Benachrichtigungen zum Lebenszyklusmanagement (Lifecycle Management, LCM) von Tokens werden von der Google Pay Online API an die tokenUpdateUrl gesendet, die bei der ursprünglichen Transaktion angegeben wurde. Sie werden gesendet, wenn ein Token deaktiviert oder gelöscht wird. Sie werden auch auf Best-Effort-Basis mit Wiederholungen für fehlgeschlagene Zustellungen gesendet. Hier ein Beispiel für den LCM-Ablauf, wenn ein Nutzer eine Karte aus Google Wallet entfernt:

MerchantTokenUpdateNotificationRequest

Eine HTTP POST-Nachricht von der Google Pay Online API mit einem JSON-Text, der eine verschlüsselte Nutzlast enthält. Die Nutzlast ist mit Ihrem gemeinsamen öffentlichen Verschlüsselungsschlüssel verschlüsselt und mit dem privaten Schlüssel von Google signiert. Sie können sie mit Ihrem privaten Verschlüsselungsschlüssel entschlüsseln und mit dem Root-Signaturschlüssel von Google überprüfen. Das Format dieses verschlüsselten Nutzlast-Wrappers ist identisch mit dem, was Sie als das PaymentMethodToken erhalten. Sie können dieselbe Bibliothek verwenden, um diese LCM-Benachrichtigung zu entschlüsseln. In der verschlüsselten Nutzlast befindet sich ein MerchantTokenUpdateNotificationRequest-Objekt, wie hier beschrieben.

Attribut Typ Erforderlich Beschreibung
messageId String Erforderlich

Eindeutige ID dieser Benachrichtigung zur Deduplizierung der Nachrichten und zu Debugging-Zwecken.

Wenn diese Benachrichtigung nicht zugestellt wird, bleibt sie für zukünftige Wiederholungen gleich.
targetNotificationUrl String Erforderlich

Die beabsichtigte URL für diese Benachrichtigung. Sie müssen bestätigen, dass diese URL der beabsichtigte Endpunkt für den Empfang von Token-LCM-Benachrichtigungen von Google Pay ist.
timestamp String Erforderlich

Zeitstempel, wann diese Benachrichtigung ursprünglich erstellt wurde. Er bleibt für zukünftige Wiederholungen gleich.

Wenn Sie mehrere Benachrichtigungen für dieselbe Token-ID erhalten, gilt nur die Benachrichtigung mit dem neuesten Zeitstempel als korrekt.
apiVersion Integer Erforderlich Hauptversion der API.
apiVersionMinor Integer Erforderlich Nebenversion der API.
merchantTokenId String Erforderlich Die Händler-Token-ID mit einer Aktualisierung. Dies ist die ID, die ursprünglich zurückgegeben wurde, als der Nutzer den Google Pay-Ablauf für die Händler-Initiierte Transaktion (Merchant-Initiated Transaction, MIT) abgeschlossen hat. Dies ist ein Feld in der verschlüsselten Nutzlast, gesendet im Card -Objekt.
cardUpdateInfo CardUpdateInfo Erforderlich Enthält Aktualisierungen für das Token.

CardUpdateInfo

Attribut Typ Erforderlich Beschreibung
fpanSuffix String Bedingt

Eine Beschreibung, mit der Nutzer die zugrunde liegende Zahlungskartennummer (Funding Primary Account Number, FPAN) identifizieren können. Es ist ein vierstelliger String, der die letzten vier Zeichen der FPAN enthält.

Wenn er vorhanden ist, kann davon ausgegangen werden, dass der Token-Status aktiv ist.

Er ist nicht vorhanden, wenn keine Änderung vorliegt.
tokenState String(Enum) Bedingt

Der neue Status des Tokens, wenn er sich seit der ersten Transaktion oder der vorherigen Benachrichtigung geändert hat.

Er ist nicht vorhanden, wenn keine Änderung vorliegt.

Der gültige Wert ist DISABLED.

MerchantTokenUpdateNotificationResponse

HTTP-Antwortcodes

HTTP-Antwortcode Nutzung
200 Die Benachrichtigung wurde erfolgreich empfangen. Zusätzliche Statusinformationen können im Antworttext als JSON-Objekt angegeben werden, wie in der nächsten Tabelle beschrieben.
401 Das targetNotificationUrl in der MerchantTokenUpdateNotificationRequest ist ungültig. Alle zukünftigen Benachrichtigungen für dieses Token können deaktiviert werden.
5xx Vorübergehender Serverfehler. Die Benachrichtigung sollte später noch einmal gesendet werden.
Sonstiges Fehler, der nicht wiederholt werden kann. Die Benachrichtigung sollte nicht noch einmal gesendet werden.
Attribut Typ Erforderlich Beschreibung
requestMessageId String Erforderlich

Die aus der Anfrage generierte Nachrichten-ID.

Sie muss mit der Nachrichten-ID aus der Anfrage übereinstimmen. Andernfalls kann die Antwort ignoriert und zukünftige Benachrichtigungen für dieses Token beendet werden.
status String(Enum) Erforderlich

Der Händler oder Zahlungsdienstanbieter (Payment Service Provider, PSP) kann einen Status zurückgeben, der ihre Erfassung der Benachrichtigung und ihre Verwendung des Tokens widerspiegelt.

Gültige Werte sind:

  • SUCCESS
  • TOKEN_NOT_IN_USE
  • TOKEN_NOT_FOUND

Beispiel

Lebenszyklusbenachrichtigung

Benachrichtigungsanfrage

Dies ist die HTTP POST-Anfrage, die die Token-LCM-Benachrichtigung enthält, die von Google Pay an Ihren Endpunkt gesendet wird. Der Text ist eine verschlüsselte Nutzlast.

HTTP-Anfrage

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

Entschlüsselte 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"
    }
  }

Benachrichtigungsantwort

  HTTP 200 OK
  Content-Type: application/json

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

Mit Ihrem tokenUpdateUrl-Endpunkt testen

Im TEST-Modus sendet Google Pay eine Token-LCM-Benachrichtigung an Ihre tokenUpdateUrl. So lösen Sie dies aus:

  • Führen Sie eine Testtransaktion aus, indem Sie loadPaymentData mit einem *TransactionInfo Objekt aufrufen und das Feld tokenUpdateUrl mit der URL Ihres Endpunkts ausfüllen.
  • Der Google-Dienst sendet eine Token-LCM-Benachrichtigung an Ihren Endpunkt.
  • Prüfen Sie, ob Sie die Benachrichtigung mit Ihrem privaten Schlüssel entschlüsseln können. Im TEST-Modus werden bei dieser Benachrichtigung die letzten vier Ziffern der Kartennummer immer in „1234“ geändert und sie enthält "tokenState": "DISABLED", unabhängig vom Token in der Anfrage.