Per consentire agli utenti di effettuare il checkout, devi implementare l'integrazione del checkout nativo. Ciò comporta la creazione di un'API REST standard che consente a Google di gestire in modo programmatico il flusso di checkout con i tuoi server. Questo metodo offre l'esperienza più fluida per gli utenti. Inizialmente, Google eseguirà il rendering dell'interfaccia utente per l'acquirente, con piani futuri per supportare esperienze più autonome.
Flusso di checkout
L'integrazione nativa richiede la creazione di un'API RESTful che Google possa chiamare per creare e gestire le sessioni di pagamento.
Il flusso generale è il seguente:
- Crea sessione di pagamento:l'utente e, facoltativamente, un agente si trovano in un ciclo di aggiunta di articoli alla sessione.
- Trasferimento a una UI di Google:una volta che l'utente decide di eseguire il pagamento, l'agente (se coinvolto) passa il controllo a una UI di Google (trasmettendo i dati della sessione di pagamento)
- Pagamento manuale:l'utente ora interagisce solo con l'interfaccia utente di Google per compilare i dettagli sensibili di evasione e pagamento e inviare l'ordine. L'agente non è coinvolto in questa parte, garantendo il determinismo.
- Completamento e reso:l'interfaccia utente di Google mostra una pagina di ringraziamento per confermare l'ordine. Facoltativamente, l'utente può essere reindirizzato all'agente, che potrebbe aver già ricevuto una notifica dell'acquisto completato.
Ciclo di vita dello stato della sessione di pagamento
Man mano che l'utente avanza nel flusso di pagamento, devi aggiornare la sessione di pagamento status per riflettere il suo stato attuale. La sessione segue il seguente ciclo di vita:
incomplete: lo stato iniziale quando viene creata una sessione. Ciò indica che mancano informazioni obbligatorie (come metodi di spedizione, tasse o dettagli utente) o che non sono state calcolate.ready_for_payment: lo stato da utilizzare dopo che l'utente ha aggiornato il proprio indirizzo di spedizione e hai calcolato le opzioni e i totali di spedizione, ma prima che lo strumento di pagamento venga finalizzato.ready_for_complete: lo stato da utilizzare durante l'idratazione completa dell'oggetto di pagamento, una volta selezionato lo strumento di pagamento e con tutti i dettagli dell'ordine convalidati.completed: lo stato finale restituito dopo l'elaborazione del pagamento e l'inserimento dell'ordine.canceled: lo stato restituito se la sessione di pagamento viene interrotta.error: lo stato restituito se un errore di logica di business non recuperabile impedisce il pagamento. Questo stato è disponibile nella versione2026-04-08e successive di UCP.
Flusso di pagamento multi-articolo:
Google ora supporta più elementi pubblicitari distinti in un'unica sessione di pagamento. Il flusso generale è il seguente:
- L'utente avvia il pagamento da un'interfaccia abilitata per UCP (ad es. facendo clic su "Acquista ora" su un prodotto).
- Viene effettuata la chiamata
POST /checkout-sessions, inclusi tutti gli elementi distinti nell'arrayline_items. L'arrayline_itemsconterrà un oggetto separato per ogni articolo univoco in fase di pagamento. - L'utente può aggiornare lo strumento di pagamento, i dettagli di evasione o applicare
sconti utilizzando le chiamate
PUT /checkout-sessions/{id}. - Quando l'utente fa clic sul pulsante "Paga con GPay", viene effettuata la chiamata
POST /checkout-sessions/{id}/complete.
Autenticazione
Per informazioni dettagliate sulla protezione degli endpoint API Native Checkout, inclusi i metodi di autenticazione supportati come chiavi API e OAuth 2.0, consulta la guida Autenticazione e sicurezza.
Strumenti per sviluppatori
Per facilitare l'implementazione dell'API Native Checkout, puoi trovare le seguenti risorse nel repository GitHub di Universal Commerce Protocol:
- Repository GitHub di UCP: esplora il repository principale per documentazione completa, specifiche e risorse della community.
- SDK:utilizza i Software Development Kit per accelerare l'integrazione. Sono disponibili SDK specifici per lingua, tra cui:
Test di conformità:convalida gli endpoint API in base alla specifica UCP utilizzando la suite di test di conformità
In questo modo, ti assicuri che l'implementazione soddisfi gli standard e i comportamenti richiesti.
Ti consigliamo vivamente di utilizzare questi strumenti per semplificare il processo di sviluppo e test.
Obiettivi del livello di servizio
I seguenti obiettivi del livello di servizio (SLO) si applicano agli endpoint API REST Native Checkout. Le attività che si integrano con Google devono soddisfare questi target per il rendimento e la disponibilità delle API.
| Endpoint | Disponibilità | Latenza (50° percentile) | Latenza (95° percentile) |
|---|---|---|---|
POST /checkout-sessions (Crea) |
>= 95% | <= 1 secondo | <= 4 secondi |
PUT /checkout-sessions/{id} (aggiornamento) |
>= 95% | <= 1 secondo | <= 5 secondi |
POST /checkout-sessions/{id}/complete (completato) |
>= 95% | <= 6 secondi | <= 10 secondi |
La latenza del 50° percentile indica che almeno il 50% delle richieste dovrebbe essere completato entro questo periodo di tempo. La latenza del 95° percentile indica che almeno il 95% delle richieste dovrebbe essere completato entro questo periodo di tempo.
Passaggi successivi
Visualizza i payload dell'API Checkout e i dettagli di implementazione tecnica per la tua versione di UCP:
- API REST per il checkout nativo versione 2026-04-08
- API REST per il checkout nativo versione 2026-01-23
Se esegui l'integrazione come fornitore di servizi di terze parti, vai alla configurazione del servizio di pagamento UCP per ospitare i profili commerciante e configurare gli handshake delle relazioni tra account.