Specifiche del gestore dei pagamenti di Google Pay

Handler Name: com.google.pay
Versione: 2026-01-11

1. Introduzione

Il gestore com.google.pay consente alle attività di offrire Google Pay come opzione di pagamento rapido tramite piattaforme compatibili con UCP. L'API Google Pay consente un checkout rapido dando agli utenti l'accesso ai metodi di pagamento memorizzati nel loro Account Google.

Questo gestore consente un modello di integrazione headless in cui le attività forniscono la configurazione di Google Pay (ad esempio i circuiti di carte consentiti e i parametri del gateway) e le piattaforme gestiscono l'interazione lato client con l'API Google Pay per generare un token di pagamento sicuro.

1.1 Vantaggi principali

Configurazione universale:le attività configurano Google Pay una sola volta utilizzando JSON standard, consentendo a qualsiasi piattaforma autorizzata di eseguire il rendering dell'interfaccia di pagamento senza codice frontend personalizzato.
Frontend disaccoppiato:le piattaforme gestiscono la complessità dell'integrazione dell'API o dell'SDK JavaScript di Google Pay, mentre le attività consumano il token risultante.
Tokenizzazione sicura:sfrutta la tokenizzazione integrata di Google per trasmettere le credenziali criptate direttamente al fornitore di servizi di pagamento (PSP) dell'attività.

2. Integrazione aziendale

2.1 Requisiti

Prima di pubblicizzare Google Pay tramite UCP, le attività devono:

Ottieni l'ID commerciante Google Pay:obbligatorio per l'elaborazione nell'ambiente PRODUCTION (registrati nella Console di Google Pay e Wallet).
Verifica del supporto del PSP:assicurati che il tuo fornitore di servizi di pagamento (PSP) sia presente nell'elenco dei processori e dei gateway supportati per la tokenizzazione di Google Pay.

2.2 Configurazione del gestore

Le attività pubblicizzano il supporto di Google Pay includendo l'handler nell'array dei gestori di pagamenti. La configurazione segue rigorosamente la struttura richiesta per inizializzare l'API Google Pay.

2.2.1 Schema di configurazione

L'oggetto di configurazione definisce l'ambiente, l'identità aziendale e i metodi di pagamento consentiti.

Metodo di pagamento Google Pay

In base a PaymentMethod di Google Pay.

Specifica di tokenizzazione

In base alla TokenizationSpecification di Google Pay.

2.2.2 Dichiarazione del gestore di esempio

{
  "payment": {
    "handlers": [
      {
        "id": "8c9202bd-63cc-4241-8d24-d57ce69ea31c",
        "name": "com.google.pay",
        "version": "2026-01-11",
        "spec": "https://pay.google.com/gp/p/ucp/2026-01-11/",
        "config_schema": "https://pay.google.com/gp/p/ucp/2026-01-11/schemas/config.json",
        "instrument_schemas": [
          "https://pay.google.com/gp/p/ucp/2026-01-11/schemas/card_payment_instrument.json"
        ],
        "config": {
          "api_version": 2,
          "api_version_minor": 0,
          "environment": "TEST",
          "merchant_info": {
            "merchant_name": "Example Merchant",
            "merchant_id": "01234567890123456789",
            "merchant_origin": "checkout.merchant.com"
          },
          "allowed_payment_methods": [
            {
              "type": "CARD",
              "parameters": {
                "allowed_auth_methods": ["PAN_ONLY"],
                "allowed_card_networks": ["VISA", "MASTERCARD"]
              },
              "tokenization_specification": {
                "type": "PAYMENT_GATEWAY",
                "parameters": {
                  "gateway": "example",
                  "gatewayMerchantId": "exampleGatewayMerchantId"
                }
              }
            }
          ]
        }
      }
    ]
  }
}

2.3 Entità

2.3.1 Schema dello strumento

Lo strumento Google Pay (card_payment_instrument) estende lo strumento di pagamento di base Card Payment Instrument. Eredita i campi di visualizzazione standard (come brand e last_digits) per garantire un rendering coerente della ricevuta, perfezionando il campo credential per contenere il payload di tokenizzazione specifico di Google Pay.

Comportamento della piattaforma: la piattaforma è responsabile del mapping della risposta Google Pay PaymentMethodData in questa struttura prima di inviarla all'attività.

Nome	Tipo	Obbligatorio	Descrizione
id	stringa	Sì	Un identificatore univoco per questo strumento di pagamento, assegnato dalla piattaforma.
handler_id	stringa	Sì	Identificatore per l'handler Google Pay.
tipo	stringa	Sì	Costante = `card`. Indica che questo strumento si comporta come una carta (eredita i campi di visualizzazione della carta).
brand	stringa	Sì	Il circuito di pagamento (ad es. `visa`, `mastercard`). Mappato da `info.cardNetwork` di Google Pay.
last_digits	stringa	Sì	Le ultime 4 cifre della carta. Mappato da `info.cardDetails` di Google Pay.
rich_text_description	stringa	No	Una descrizione facoltativa in formato RTF della scheda (ad es. "Visa che termina con 1234, scade a dicembre 2025").
rich_card_art	stringa (uri)	No	Un URI facoltativo a un'immagine avanzata che rappresenta la carta (ad es. l'immagine della carta dell'emittente).
billing_address	Indirizzo postale	No	L'indirizzo di fatturazione associato alla carta.
credenziale	Payload delle credenziali	No	I dati di tokenizzazione sicuri restituiti da Google Pay.

Payload delle credenziali

Questo oggetto funge da credential per lo strumento. Corrisponde direttamente ai dati di tokenizzazione di Google Pay.

Indirizzo postale

Questo oggetto funge da campo address. Corrisponde direttamente a PostalAddress.

3. Integrazione della piattaforma

3.1 Requisiti

Prima di gestire i pagamenti com.google.pay, le piattaforme devono:

Essere in grado di caricare l'API Google Pay per il web (o l'equivalente per Android).
Rispetta le linee guida per il brand Google Pay quando esegui il rendering del pulsante di pagamento.

3.2 Protocollo di pagamento

Le piattaforme DEVONO seguire questo flusso per elaborare l'handler:

Passaggio 1: scopri e configura

La piattaforma inizializza il client per gestire il ciclo di vita dell'API.

Reference: PaymentsClient

Passaggio 2: controlla la funzionalità Paga e ricevi

La piattaforma verifica se l'utente è in grado di effettuare un pagamento con i metodi di pagamento specificati prima di visualizzare il pulsante.

Riferimento: isReadyToPay

Passaggio 3: crea la richiesta di pagamento

La piattaforma assembla l'oggetto richiesta di dati di pagamento, inclusi la configurazione del commerciante, i metodi di pagamento e i dettagli della transazione (prezzo e valuta).

Reference: PaymentDataRequest

Passaggio 4: richiama l'interazione dell'utente

La piattaforma attiva la visualizzazione del foglio di pagamento quando l'utente interagisce con il pulsante di pagamento.

Reference: loadPaymentData

Passaggio 5: completa il check-out

In caso di interazione riuscita dell'utente, l'API Google Pay restituisce un oggetto PaymentInstrument nella chiave payment_data. La piattaforma mappa questa risposta allo schema card_payment_instrument e invia la richiesta di completamento del pagamento.

POST /checkout-sessions/{checkout_id}/complete

{
  "payment_data": {
    "id": "pm_1234567890abc",
    "handler_id": "8c9202bd-63cc-4241-8d24-d57ce69ea31c",
    "type": "card",
    "brand": "visa",
    "last_digits": "4242",
    "billing_address": {
      "street_address": "123 Main Street",
      "extended_address": "Suite 400",
      "address_locality": "Charleston",
      "address_region": "SC",
      "postal_code": "29401",
      "address_country": "US",
      "first_name": "Jane",
      "last_name": "Smith"
    },
    "credential": {
      "type": "PAYMENT_GATEWAY",
      "token": "{\"signature\":\"...\",\"protocolVersion\":\"ECv2\"...}"
    }
  },
  "risk_signals": {
      ...
  }
}

4. Elaborazione aziendale

Al ricevimento di uno strumento di pagamento Google Pay, le attività DEVONO:

Validate Handler: conferma che handler_id corrisponde all'handler Google Pay.
Estrai token: recupera la stringa del token da payment_data.credential.token.
Elabora pagamento:passa la stringa del token e i dettagli della transazione all'endpoint del PSP.
- Nota: la maggior parte dei PSP dispone di un campo specifico per un "payload Google Pay" o un "token di rete".
Risposta di reso:rispondi con lo stato finale del pagamento (operazione riuscita/non riuscita).

5. Considerazioni sulla sicurezza

5.1 Sicurezza dei token

PAYMENT_GATEWAY::quando utilizzi questo tipo di tokenizzazione, il token viene criptato appositamente per la parte che esegue la tokenizzazione. La parte pass-through non può decriptare questo token e deve passarlo alla parte di tokenizzazione così com'è.
DIRETTO:se utilizzi la tokenizzazione DIRECT, l'attività riceve dati della carta criptati che deve decriptare. Ciò aumenta significativamente l'ambito di conformità PCI DSS e in genere non è consigliato, a meno che l'attività non sia un fornitore di servizi conforme allo standard PCI di livello 1.

5.2 Isolamento dell'ambiente

Modalità TEST:nell'ambiente TEST, Google Pay restituisce token fittizi. Questi non possono essere addebitati.
Modalità PRODUZIONE:vengono utilizzate carte reali. Le attività devono assicurarsi che le credenziali del PSP in config.allowed_payment_methods corrispondano all'ambiente.

Indietro

Acquisto rapido incorporato (facoltativo)

Avanti

Collegamento delle identità (facoltativo)

Specifiche del gestore dei pagamenti di Google Pay Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.