Metodi di pagamento > Wallet > Google Pay

Google Pay

Google Pay è il portafoglio digitale offerto da Google per memorizzare le proprie carte e pagare in modo veloce e sicuro.

Attivazione

Per rendere disponibile questo metodo di pagamento sulla pagina di cassa, è necessario configurare e attivare il servizio accedendo alla pagina dedicata a Google Pay del back office. Non è necessaria una registrazione a Google.

Pagamento

Il pagamento con Google Pay è compatibile e segue le specifiche delle seguenti modalità di integrazione:

Di seguito una tabella riassuntiva delle compatibilità e dei possibili limiti del metodo di pagamento con i servizi forniti dal gateway XPay:

Paesi	Globale
Minimo importo	Nessun limite
Massimo importo	Nessun limite
Pagamento	Si
Preautorizzazione	Si
Termine massimo preautorizzazione	27 giorni
Contabilizzazione implicita	Si
Contabilizzazione esplicita	Si
Termine massimo contabilizzazione esplicita	5 giorni
Recurring	No
OneClick	No
Rimborso totale	Si
Rimborso parziale	Si
Rimborsi parziali multipli	Si
Termine massimo rimborso	365 giorni

Integrazione tramite API Google

Attraverso questo metodo, Nexi si occuperà solamente dell'autorizzazione del pagamento; i dati relativi a Google Pay verranno raccolti dal sito o dall'app dell'esercente, che invierà il JSON ricevuto da Google a Nexi tramite l'API:

POST /orders/googlepay

Per utilizzare questo servizio, è necessario seguire la guida ufficiale all'integrazione delle Google Pay API. Per integrare Google Pay, è necessario che l'esercente aderisca ai termini di servizio dell'API di Google, alla Politica d'uso e alle linee guida sul marchio: https://developers.google.com/pay/api/web/guides/brand-guidelines.

Di seguito il flusso di pagamento:

Inizio del pagamento: l'utente clicca sul pulsante Google Pay.
Selezione della carta dal wallet: si attiva l'interfaccia nativa di Google Pay (Google Wallet), che mostra all'utente le carte memorizzate sul proprio account o dispositivo.
Generazione del token: l'utente seleziona la carta e si autentica, se richiesto dal dispositivo (sblocco biometrico o codice). Google Pay restituisce un token di pagamento al front-end del sito web.
Invio al backend: il front-end del sito web trasmette il token di pagamento e i dettagli dell'ordine al proprio backend.
Autorizzazione tramite Nexi: il backend elabora la transazione e invia il token a Nexi per l'addebito tramite l'API:
POST /orders/googlepay

Durante l'integrazione, Google richiederà tramite l'oggetto "tokenizationSpecification" le informazioni sul provider di pagamento utilizzato durante la fase autorizzativa. Di seguito sono riportati i dati da impostare:

"gateway": "nexigtw"
"gatewayMerchantId": "" → generare un UUID e utilizzarlo come identificativo fisso. Lo stesso valore deve essere riutilizzato per tutte le chiamate, senza rigenerarlo ad ogni richiesta. È sufficiente che sia univoco.

Il comportamento dell'API POST /orders/googlepay varia nel suo utilizzo a seconda di come Google Pay restituisce il payload con i dati di pagamento:

Payload con pan tokenizzato (CRYPTOGRAM_3DS): l'API XPay eseguirà il pagamento completando la transazione. Si rientra in questa casistica quando il pagamento viene effettuato da un dispositivo Android con applicazione Google Wallet installata e carta registrata. È anche necessario che sul dispositivo sia impostata un'autenticazione (blocco schermo) di livello adeguato.
Di seguito un'esempio di risposta:

{ "operation": { "additionalData": { "functionCode": "101", "maskedPan": "411111******1112", "cardCountry": { "alpha3Code": "ITA", "alpha2Code": "IT", "italy": true, "description": "ITALY", "code": "380", "sqlValue": "380" }, "authorizationCode": "600806", "cardType": "MONETA", "authorizationStatus": "000", "cardId4": "EwmGJbC4NG1MTP5LdKpgzsd/P9Sjuugx+OyPgEWuChc=", "tokenization": "GOOGLE_PAY", "rrn": "433388888888", "messageReasonCode": "1510", "trn": "PDV", "omnichannelId": "MZSBXTFI08001260710-15176189880110001", "posDataCode": "100050J00100", "installmentQty": 0, "securityType": "1", "cardId": "04c447dce14bbbcbbc5aad3d2b512ae52782fe407ea37128cc91f2483d70ba52", "authMethod": "CRYPTOGRAM_3DS", "cardBrand": "VISA" }, "channel": "ECOMMERCE", "customerInfo": { "recontactConsent": false }, "operationAmount": "200", "operationCurrency": "EUR", "operationId": "785768057300861919", "operationResult": "AUTHORIZED", "operationTime": "2026-07-10 15:39:43.485", "operationType": "AUTHORIZATION", "orderId": "order-1783690783", "paymentCircuit": "GOOGLE_PAY", "paymentEndToEndId": "600806", "paymentInstrumentInfo": "***1112", "paymentMethod": "APM", "warnings": [] }, "paymentFlow": "CRYPTOGRAM" }

Per i dettagli sul contenuto dell'oggetto, fare riferimento allo schema della risposta (Response) dell'API GET /operations/{operationId}.
Payload con clear pan (PAN reale, PAN_ONLY): l'API XPay non eseguirà direttamente il pagamento, ma restituirà i dati necessari per eseguire l'autenticazione 3D Secure. Si rientra in questo scenario nei casi che non rientrano nella casistica CRYPTOGRAM_3DS, ad esempio quando il pagamento viene effettuato da un PC Windows o da un dispositivo iOS.
Di seguito viene descritto il flusso.

Flusso PAN_ONLY

Per consentire ai clienti di pagare con questa modalità, è necessario configurare lato Google la costante:

È inoltre obbligatorio includere nella chiamata API POST /orders/googlepay i seguenti parametri:

resultUrl
notificationUrl
cancelUrl

Questi campi sono necessari per gestire l’esito della transazione al termine dell’autenticazione 3D Secure.

Dopo la ricezione del token da Google e la successiva chiamata all’API POST /orders/googlepay, verrà restituito il seguente oggetto:

                                        {
    "paymentFlow": "PAN_ONLY",
    "iframe": {
        "fields": [
            {
                "class": "GDI",
                "id": "GDI",
                "src": "https://xpaysandbox.nexigroup.com/phoenix-0.0/iframe.html?id=gdi&lang=ITA&correlationid=0e15ef60-22e3-404a-87ca-e0bba6b00a56...",
                "type": "GDI"
            }
        ],
        "sessionId": "e0c81f5e-2c06-454a-b10b-6b919258fa9a",
        "state": "GDI_VERIFICATION"
    }
}
                                    

È necessario creare un nuovo layout di pagina HTML, con un singolo frame interno, per consentire al server 3D Secure di raccogliere dati sensibili del browser necessari per valutare il rischio della transazione. Il contenuto dell'iframe dovrà essere l'url indicato nel parametro "src".

                                        <div>
    <iframe hidden src=" https://xpaysandbox.nexigroup.com/phoenix-0.0/iframe.html?id=gdi&lang=ITA&correlationid=0e15ef60-22e3-404a-87ca-e0bba6b00a56..."/>
</div>
                                    

In questo caso, il frame può rimanere nascosto poiché la pagina caricata non mostra alcuna informazione.
L'operazione può richiedere da 2 a 10 secondi, quindi è opportuno mostrare un caricamento per far sapere all'utente che qualcosa sta accadendo in background.
L'iframe comunicherà il completamento della raccolta dati tramite un evento; per la gestione di queste comunicazioni è necessario includere l'SDK Nexi nella pagina. Inserire questa dichiarazione in un punto qualsiasi della pagina, sostituendo "nexiDomain" con il dominio di sandbox (https://xpaysandbox.nexigroup.com) o di produzione (https://xpay.nexigroup.com) di XPay:

                                        <script type="text/javascript" src="{nexiDomain}/monetaweb/resources/hfsdk.js"></script>
                                    

Al termine della fase GDI, si potrà entrare in una delle seguenti due casistiche:

Autenticazione 3D Secure: il pagamento richiede l'autenticazione forte (SCA - Strong Customer Authentication) da parte del titolare carta. Verrà restituito l'evento onBuildFlowStateChange contenente l'indirizzo di autenticazione 3D Secure, verso il quale il cliente dovrà essere reindirizzato:

{ "event": "BUILD_FLOW_STATE_CHANGE", "state": "READY_FOR_PAYMENT", "data": { "state": "REDIRECTED_TO_EXTERNAL_DOMAIN", "url": "https://xpaysandbox.nexigroup.com/authorization-stub/ui/threeds/one/5069aec8-97bb-4c92-ae2e-5d9210ac948f/auth" } }
- evtData.data.state: valorizzato con "REDIRECTED_TO_EXTERNAL_DOMAIN".
- evtData.data.url: indirizzo di autenticazione 3D Secure, verso il quale il cliente dovrà essere reindirizzato.
Il reindirizzamento verso la pagina esterna consentirà al cliente di completare l'eventuale autenticazione richiesta dalla banca e, al contempo, permetterà al gateway XPay di concludere il pagamento.

Per la gestione dell'esito, verranno utilizzati gli URL configurati nei parametri inviati nella chiamata iniziale API POST /orders/googlepay:
- resultUrl
- notificationUrl
- cancelUrl
Esito pagamento: la transazione non richiede autenticazione 3D Secure da parte del titolare carta, il pagamento viene quindi eseguito. Vengono restituiti i parametri:

"operation": oggetto contenente il dettaglio dell'operazione. Per i dettagli sul contenuto dell'oggetto, fare riferimento allo schema della risposta (Response) dell'API GET /operations/{operationId}.
"state": valorizzato con "PAYMENT_COMPLETE". Attenzione: lo stato indica solamente che il processo di pagamento è terminato, non che la transazione sia andata a buon fine. Per risalire al reale esito del pagamento, verificare il parametro "operationResult" presente nell'oggetto "operation" sopra indicato.