Powiadomienia dotyczące zarządzania cyklem życia tokena

Przegląd

Przyszłe powiadomienia dotyczące zarządzania cyklem życia tokena (LCM) są wysyłane z Google Pay Online API na adres tokenUpdateUrl podany w momencie pierwotnej transakcji. Są one wysyłane, gdy token zostanie dezaktywowany lub usunięty. Są one też wysyłane zgodnie z zasadą najlepszych starań, a w przypadku nieudanych dostaw podejmowane są ponowne próby. Oto przykład procesu LCM, gdy użytkownik usunie kartę z Portfela Google:

MerchantTokenUpdateNotificationRequest

Wiadomość HTTP POST z Google Pay Online API zawiera treść JSON, która obejmuje zaszyfrowany ładunek. Ładunek jest szyfrowany za pomocą udostępnionego klucza publicznego szyfrowania i podpisywany kluczem prywatnym Google. Możesz odszyfrować dane za pomocą prywatnego klucza szyfrowania i zweryfikować je za pomocą głównego klucza podpisywania Google. Ten zaszyfrowany format opakowania ładunku jest identyczny z formatem, który możesz otrzymać jako PaymentMethodToken. Do odszyfrowania tego powiadomienia LCM możesz użyć tej samej biblioteki. W zaszyfrowanym ładunku znajduje się obiekt MerchantTokenUpdateNotificationRequest, o którym więcej informacji znajdziesz tutaj.

Właściwość Typ Czy jest wymagana Opis
messageId ciąg znaków Wymagane

Unikalny identyfikator tego powiadomienia, który służy do usuwania duplikatów wiadomości i do debugowania.

Jeśli to powiadomienie nie zostanie dostarczone, pozostanie takie samo w przypadku kolejnych prób.
targetNotificationUrl ciąg znaków Wymagane

Docelowy adres URL tego powiadomienia. Aby otrzymywać z Google Pay powiadomienia o cyklu życia tokena, musisz potwierdzić, że ten adres URL jest Twoim docelowym punktem końcowym.
timestamp ciąg znaków Wymagane

Sygnatura czasowa utworzenia tego powiadomienia. Pozostaje ona taka sama w przypadku kolejnych prób.

Jeśli otrzymasz kilka powiadomień dotyczących tego samego identyfikatora tokena, za prawidłowe uznawane jest tylko powiadomienie z najnowszą sygnaturą czasową.
apiVersion int Wymagane Główna wersja interfejsu API.
apiVersionMinor int Wymagane Wersja podrzędna interfejsu API.
merchantTokenId Ciąg znaków Wymagane Identyfikator tokena sprzedawcy z aktualizacją. Jest to identyfikator zwrócony pierwotnie, gdy użytkownik zakończył proces Google Pay w przypadku MIT. Jest to pole w zaszyfrowanym ładunku wysyłanym w obiekcie Obiekt Card.
cardUpdateInfo CardUpdateInfo Wymagane Zawiera aktualizacje tokena.

CardUpdateInfo

Właściwość Typ Czy jest wymagana Opis
fpanSuffix ciąg znaków Warunkowy

Opis, który pomaga użytkownikom zidentyfikować podstawowy numer głównego instrumentu płatności (FPAN). Jest to 4-cyfrowy ciąg znaków zawierający 4 ostatnie znaki numeru FPAN.

Jeśli jest obecny, stan tokena można uznać za aktywny.

Nie występuje, jeśli nie ma zmian.
tokenState string(enum) Warunkowy

Nowy stan tokena, jeśli uległ zmianie od czasu pierwszej transakcji lub poprzedniego powiadomienia.

Nie występuje, jeśli nie ma zmian.

Prawidłowa wartość to DISABLED.

MerchantTokenUpdateNotificationResponse

Kody odpowiedzi HTTP

Kod odpowiedzi HTTP Wykorzystanie
200 Powiadomienie zostało odebrane. Dodatkowe informacje o stanie mogą być podane w treści odpowiedzi w postaci obiektu JSON, jak opisano w tabeli poniżej.
401 Element targetNotificationUrl w MerchantTokenUpdateNotificationRequest jest nieprawidłowy. Wszystkie przyszłe powiadomienia dotyczące tego tokena można wyłączyć.
5xx Tymczasowy błąd serwera. Powiadomienie należy wysłać ponownie w późniejszym czasie.
Inne Błąd, którego nie można ponowić. Powiadomienie nie powinno być ponownie wysyłane w późniejszym czasie.
Właściwość Typ Czy jest wymagana Opis
requestMessageId ciąg znaków Wymagane

Identyfikator wiadomości wygenerowany na podstawie żądania.

Musi on być zgodny z identyfikatorem wiadomości z żądania. W przeciwnym razie odpowiedź może zostać zignorowana, a przyszłe powiadomienia dotyczące tego tokena zostaną wstrzymane.
status string(enum) Wymagane

Sprzedawca lub dostawca usług płatniczych (PSP) może zwrócić stan, który odzwierciedla przyjęcie powiadomienia i użycie tokena.

Prawidłowe wartości to:

  • SUCCESS
  • TOKEN_NOT_IN_USE
  • TOKEN_NOT_FOUND

Przykład

Powiadomienie o cyklu życia

Prośba dotycząca powiadomienia

Jest to żądanie HTTP POST zawierające powiadomienie o tokenie LCM, które jest wysyłane z Google Pay do Twojego punktu końcowego. Treść to zaszyfrowany ładunek.

Żądanie 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"
    }
  }

Odpowiedź na powiadomienie

  HTTP 200 OK
  Content-Type: application/json

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

Testowanie za pomocą punktu końcowego tokenUpdateUrl

W trybie TEST Google Pay wysyła powiadomienie LCM tokena na urządzenie tokenUpdateUrl. Aby to zrobić, wykonaj te czynności:

  • Przeprowadź transakcję testową, wywołując loadPaymentData z obiektem *TransactionInfo i wypełniając pole tokenUpdateUrl adresem URL punktu końcowego.
  • Usługa Google wyśle powiadomienie o cyklu życia tokena do Twojego punktu końcowego.
  • Sprawdź, czy możesz odszyfrować powiadomienie za pomocą klucza prywatnego. Pamiętaj, że w trybie TEST to powiadomienie zawsze zmieni 4 ostatnie cyfry numeru karty na „1234” i będzie zawierać "tokenState": "DISABLED" niezależnie od tokena w żądaniu.