Notificări privind gestionarea ciclului de viață al token-urilor

Prezentare generală

Notificările viitoare privind gestionarea ciclului de viață al token-urilor (LCM) sunt trimise de la API-ul Google Pay Online către URL-ul tokenUpdateUrl furnizat în momentul tranzacției inițiale. Acestea sunt trimise dacă un token este dezactivat sau șters. De asemenea, sunt trimise în baza principiului „cele mai bune eforturi”, cu reîncercări pentru livrările eșuate. Iată un exemplu de flux LCM atunci când un card este eliminat din Google Wallet de către un utilizator:

Cerere de notificare a actualizării jetonului comerciantului

Un mesaj HTTP POST de la API-ul Google Pay Online conține un corp JSON care încapsulează o sarcină utilă criptată. Sarcina utilă este criptată cu cheia dvs. publică de criptare partajată și semnată cu cheia privată a Google. Puteți decripta cu cheia dvs. privată de criptare și verifica cu cheia de semnare rădăcină a Google . Acest format de încapsulare a sarcinii utilă criptate este identic cu ceea ce ați putea primi ca PaymentMethodToken . Puteți utiliza aceeași bibliotecă pentru a decripta această notificare LCM. În sarcina utilă criptată, există un obiect MerchantTokenUpdateNotificationRequest așa cum este detaliat aici.

Proprietate Tip Necesitate Descriere
messageId şir Necesar

ID-ul unic al acestei notificări pentru deduplicarea mesajelor și în scopuri de depanare.

Dacă această notificare nu este livrată cu succes, rămâne aceeași pentru încercările viitoare.

targetNotificationUrl şir Necesar

Adresa URL dorită pentru această notificare. Trebuie să confirmați că această adresă URL este punctul final destinat pentru a primi notificări LCM cu token-uri de la Google Pay.

timestamp şir Necesar

Marcajul temporal al momentului în care a fost creată inițial această notificare. Rămâne același pentru viitoarele încercări.

Dacă primiți mai multe notificări pentru același ID de token, numai notificarea cu cea mai recentă marcaj temporal este considerată corectă.

apiVersion întreg Necesar Versiune majoră a API-ului.
apiVersionMinor întreg Necesar Versiune minoră a API-ului.
merchantTokenId Şir Necesar ID-ul token-ului comerciantului cu o actualizare. Acesta este ID-ul returnat inițial când utilizatorul a finalizat fluxul Google Pay pentru MIT. Acesta este un câmp din sarcina criptată, trimis în Obiect Card .
cardUpdateInfo Informații actualizare card Necesar Conține actualizări pentru token.

Informații actualizare card

Proprietate Tip Necesitate Descriere
fpanSuffix şir Condiţional

O descriere care ajută utilizatorii să identifice Numărul Contului Principal de Finanțare (FPAN) subiacent. Este un șir de patru cifre care conține ultimele patru caractere ale FPAN-ului.

Când este prezent, se poate presupune că starea token-ului este activă.

Nu este prezent dacă nu există nicio schimbare.

tokenState șir(enumerare) Condiţional

Noua stare a token-ului, dacă a fost modificată de la tranzacția inițială sau de la notificarea anterioară.

Nu este prezent dacă nu există nicio schimbare.

Valoarea validă este DISABLED .

Răspuns la notificarea actualizării jetonului comerciantului

Coduri de răspuns HTTP

Cod de răspuns HTTP Utilizare
200 Notificarea a fost primită cu succes. Informații suplimentare despre stare pot fi furnizate în corpul răspunsului ca obiect JSON, așa cum este descris în tabelul următor.
401 URL-ul targetNotificationUrl din MerchantTokenUpdateNotificationRequest este nevalid. Toate notificările viitoare pentru acest token pot fi dezactivate.
5xx Eroare temporară a serverului. Notificarea ar trebui trimisă din nou mai târziu.
Alte Eroare neraportabilă. Notificarea nu ar trebui trimisă din nou ulterior.
Proprietate Tip Necesitate Descriere
requestMessageId şir Necesar

ID-ul mesajului generat în urma solicitării.

Trebuie să corespundă cu ID-ul mesajului din solicitare, altfel răspunsul poate fi ignorat, iar notificările viitoare pentru acest token vor fi oprite.

status șir(enumerare) Necesar

Comerciantul sau Furnizorul de Servicii de Plată (PSP) poate returna o stare care reflectă modul în care au preluat notificarea și utilizarea token-ului.

Valorile valide sunt:

  • SUCCESS
  • TOKEN_NOT_IN_USE
  • TOKEN_NOT_FOUND

Exemplu

Notificare privind ciclul de viață

Cerere de notificare

Aceasta este solicitarea HTTP POST care conține notificarea LCM a tokenului, trimisă de Google Pay către terminalul dvs. Corpul este o sarcină utilă criptată.

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

Cerere de notificare de actualizare a jetonului comerciantului decriptată 

  {  // 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ăspuns la notificare 

  HTTP 200 OK
  Content-Type: application/json

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

Testează cu endpoint-ul tokenUpdateUrl

În modul TEST, Google Pay trimite o notificare LCM pentru token-uri către adresa tokenUpdateUrl . Pentru a declanșa această notificare, urmați acești pași:

  • Finalizați o tranzacție de test apelând loadPaymentData cu un obiect *TransactionInfo , populând câmpul tokenUpdateUrl cu adresa URL a punctului final.
  • Serviciul Google va trimite o notificare LCM de tip token către endpoint-ul dvs.
  • Verificați dacă puteți decripta notificarea folosind cheia privată. Rețineți că, în modul TEST, această notificare va schimba întotdeauna ultimele 4 cifre ale numărului cardului în „1234” și va conține "tokenState": "DISABLED" , indiferent de token-ul din solicitare.