Notifiche di gestione del ciclo di vita dei token

Panoramica

Le future notifiche di gestione del ciclo di vita dei token (LCM) vengono inviate dall'API Google Pay Online all'tokenUpdateUrl fornito al momento della transazione originale. Vengono inviate se un token viene disattivato o eliminato. Vengono inoltre inviati secondo il criterio del "best effort" con tentativi di invio per le consegne non riuscite. Ecco un esempio di flusso LCM quando una carta viene rimossa da Google Wallet da un utente:

MerchantTokenUpdateNotificationRequest

Un messaggio HTTP POST dall'API Google Pay Online, contiene un corpo JSON che incapsula un payload criptato. Il payload è criptato con la tua chiave di crittografia pubblica condivisa e firmato con la chiave privata di Google. Puoi decriptare con la tua chiave di crittografia privata e verificare con la chiave di firma principale di Google. Questo formato wrapper del payload criptato è identico a quello che potresti ricevere come PaymentMethodToken. Puoi utilizzare la stessa libreria per decriptare questa notifica LCM. All'interno del payload criptato, è presente un oggetto MerchantTokenUpdateNotificationRequest come descritto qui.

Proprietà	Tipo	Necessità	Descrizione
messageId	stringa	Obbligatorio	ID univoco di questa notifica per deduplicare i messaggi e a scopo di debug. Se questa notifica non viene recapitata correttamente, rimane invariata per i tentativi futuri.
targetNotificationUrl	stringa	Obbligatorio	L'URL previsto per questa notifica. Devi confermare che questo URL è l'endpoint che intendi utilizzare per ricevere le notifiche LCM dei token da Google Pay. Nota:se l'URL non è di tua proprietà o non è corretto, devi rispondere con un errore HTTP 400.
timestamp	stringa	Obbligatorio	Timestamp di creazione originale di questa notifica. Rimane invariato per i tentativi futuri. Se ricevi più notifiche per lo stesso ID token, solo la notifica con il timestamp più recente è considerata accurata.
apiVersion	int	Obbligatorio	Versione principale dell'API.
apiVersionMinor	int	Obbligatorio	Versione secondaria dell'API.
merchantTokenId	Stringa	Obbligatorio	L'ID token commerciante con un aggiornamento. Questo è l'ID restituito originariamente quando l'utente ha completato il flusso di Google Pay per l'MIT. Questo è un campo all'interno del payload criptato, inviato nell'oggetto Card.
cardUpdateInfo	CardUpdateInfo	Obbligatorio	Contiene aggiornamenti per il token.

CardUpdateInfo

Proprietà	Tipo	Necessità	Descrizione
fpanSuffix	stringa	Condizionale	Una descrizione per aiutare gli utenti a identificare il numero del conto principale di finanziamento (FPAN) sottostante. È una stringa di quattro cifre che contiene gli ultimi quattro caratteri del FPAN. Quando è presente, si può presumere che lo stato del token sia attivo. Non è presente se non ci sono modifiche.
tokenState	stringa(enum)	Condizionale	Il nuovo stato del token, se è cambiato rispetto alla transazione iniziale o alla notifica precedente. Non è presente se non ci sono modifiche. Il valore valido è DISABLED.

MerchantTokenUpdateNotificationResponse

Codici di risposta HTTP

Codice di risposta HTTP	Utilizzo
200	La notifica è stata ricevuta. Ulteriori informazioni sullo stato possono essere fornite nel corpo della risposta come oggetto JSON, come descritto nella tabella seguente.
401	Il valore targetNotificationUrl in MerchantTokenUpdateNotificationRequest non è valido. Tutte le notifiche future per questo token possono essere disattivate.
5xx	Errore temporaneo del server. La notifica deve essere inviata di nuovo in un secondo momento.
Altro	Errore non riproducibile. La notifica non deve essere inviata di nuovo in un secondo momento.

Proprietà	Tipo	Necessità	Descrizione
requestMessageId	stringa	Obbligatorio	L'ID messaggio generato dalla richiesta. Deve corrispondere all'ID messaggio della richiesta, altrimenti la risposta può essere ignorata e le notifiche future per questo token vengono interrotte.
status	stringa(enum)	Obbligatorio	Il commerciante o il fornitore di servizi di pagamento (PSP) può restituire uno stato che riflette l'inserimento della notifica e l'utilizzo del token. I valori validi sono: SUCCESS TOKEN_NOT_IN_USE TOKEN_NOT_FOUND

Esempio

Notifica del ciclo di vita

Richiesta di notifica

Si tratta della richiesta POST HTTP che contiene la notifica LCM del token, inviata da Google Pay al tuo endpoint. Il corpo è un payload criptato.

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

Risposta alla notifica

  HTTP 200 OK
  Content-Type: application/json

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

Esegui il test con l'endpoint tokenUpdateUrl

In modalità TEST, Google Pay invia una notifica LCM del token al tuo tokenUpdateUrl. Per attivare questa funzionalità, segui questi passaggi:

• Completa una transazione di test chiamando loadPaymentData con un oggetto *TransactionInfo, compilando il campo tokenUpdateUrl con l'URL dell'endpoint.
  Nota:per completare la transazione e attivare la notifica in modalità TEST, devi fare clic sul pulsante Continua o Paga nel prospetto paga.
• Il servizio di Google invierà una notifica LCM del token al tuo endpoint.
• Verifica di poter decriptare la notifica utilizzando la tua chiave privata. Tieni presente che, in modalità TEST, questa notifica modificherà sempre le ultime 4 cifre del numero di carta in "1234" e conterrà "tokenState": "DISABLED", indipendentemente dal token nella richiesta.