Benachrichtigungen zur Verwaltung des Token-Lebenszyklus

Übersicht

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

MerchantTokenUpdateNotificationRequest

Eine HTTP-POST-Nachricht von der Google Pay Online API enthält einen JSON-Text, der eine verschlüsselte Nutzlast umfasst. Die Nutzlast wird mit Ihrem gemeinsamen öffentlichen Verschlüsselungsschlüssel verschlüsselt und mit dem privaten Schlüssel von Google signiert. Sie können die Daten mit Ihrem privaten Verschlüsselungsschlüssel entschlüsseln und mit dem Google-Stammsignaturschlüssel überprüfen. Dieses verschlüsselte Nutzlast-Wrapper-Format ist identisch mit dem, was Sie als PaymentMethodToken erhalten. Sie können dieselbe Bibliothek verwenden, um diese LCM-Benachrichtigung zu entschlüsseln. Die verschlüsselte Nutzlast enthält ein MerchantTokenUpdateNotificationRequest-Objekt, wie hier beschrieben.

Attribut Typ Notwendigkeit Beschreibung
messageId String Erforderlich

Eindeutige ID dieser Benachrichtigung zur Deduplizierung von Nachrichten und zur Fehlerbehebung.

Wenn diese Benachrichtigung nicht zugestellt werden kann, bleibt sie für zukünftige Wiederholungsversuche unverändert.
targetNotificationUrl String Erforderlich

Die vorgesehene URL für diese Benachrichtigung. Sie müssen bestätigen, dass diese URL Ihr vorgesehener Endpunkt ist, um Benachrichtigungen zum Lebenszyklus von Token von Google Pay zu erhalten.
timestamp String Erforderlich

Der Zeitstempel, zu dem diese Benachrichtigung ursprünglich erstellt wurde. Sie bleibt für zukünftige Wiederholungsversuche gleich.

Wenn Sie mehrere Benachrichtigungen für dieselbe Token-ID erhalten, gilt nur die Benachrichtigung mit dem neuesten Zeitstempel als korrekt.
apiVersion int Erforderlich Hauptversion der API.
apiVersionMinor int 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 das MIT abgeschlossen hat. Dies ist ein Feld in der verschlüsselten Nutzlast, die im Card-Objekt.
cardUpdateInfo CardUpdateInfo Erforderlich Enthält Aktualisierungen für das Token.

CardUpdateInfo

Attribut Typ Notwendigkeit Beschreibung
fpanSuffix String Bedingt

Eine Beschreibung, die Nutzern hilft, die zugrunde liegende Zahlungskartennummer (Funding Primary Account Number, FPAN) zu identifizieren. Es handelt sich um einen vierstelligen String, der die letzten vier Zeichen der FPAN enthält.

Wenn sie vorhanden ist, kann davon ausgegangen werden, dass der Tokenstatus aktiv ist.

Sie ist nicht vorhanden, wenn es keine Änderung gibt.
tokenState string(enum) Bedingt

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

Sie ist nicht vorhanden, wenn es keine Änderung gibt.

Gültiger Wert ist DISABLED.

MerchantTokenUpdateNotificationResponse

HTTP-Antwortcodes

HTTP-Antwortcode Nutzung
200 Die Benachrichtigung wurde empfangen. Zusätzliche Statusinformationen können im Antworttext als JSON-Objekt angegeben werden, wie in der nächsten Tabelle beschrieben.
401 Die targetNotificationUrl in MerchantTokenUpdateNotificationRequest ist ungültig. Alle zukünftigen Benachrichtigungen für diesen Code können deaktiviert werden.
5xx Vorübergehender Serverfehler. Die Benachrichtigung sollte zu einem späteren Zeitpunkt noch einmal gesendet werden.
Sonstiges Fehler, der nicht wiederholt werden kann. Die Benachrichtigung sollte nicht zu einem späteren Zeitpunkt noch einmal gesendet werden.
Attribut Typ Notwendigkeit 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 werden und zukünftige Benachrichtigungen für dieses Token werden beendet.
status string(enum) Erforderlich

Der Händler oder Zahlungsdienstleister kann einen Status zurückgeben, der die Verarbeitung der Benachrichtigung und die 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-Benachrichtigung zum Lebenszyklusmanagement enthält und 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\"}"
  }

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

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 Ihr tokenUpdateUrl. So lösen Sie dies aus:

  • Führen Sie eine Testtransaktion durch, indem Sie loadPaymentData mit einem *TransactionInfo-Objekt aufrufen und das Feld tokenUpdateUrl mit Ihrer Endpunkt-URL füllen.
  • Der Dienst von Google 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 in dieser Benachrichtigung immer die letzten vier Ziffern der Kartennummer in „1234“ geändert und "tokenState": "DISABLED" angezeigt, unabhängig vom Token in der Anfrage.