Per consentire agli utenti di effettuare il pagamento, devi implementare l'integrazione del pagamento nativo. Ciò comporta la creazione di un'API REST standard che consenta a Google di gestire in modo programmatico il flusso di pagamento 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ù agentiche.
Flusso di pagamento
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 sono in un loop che aggiunge articoli alla sessione.
- Trasferisci a un'interfaccia utente di Google: una volta che l'utente decide di effettuare il pagamento, l'agente (se coinvolto) passa il controllo a un'interfaccia utente di Google (trasmettendo i dati della sessione di pagamento).
- Pagamento manuale: ora l'utente interagisce solo con l'interfaccia utente di Google per inserire i dati sensibili di evasione e pagamento e inviare l'ordine. L'agente non è coinvolto in questa parte, garantendo il determinismo.
- Completamento e restituzione: 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 lo status della sessione di pagamento per riflettere lo stato attuale. La sessione passa attraverso il seguente ciclo di vita:
incomplete: lo stato iniziale quando viene creata una sessione. Indica che mancano o non sono stati calcolati dati obbligatori (ad esempio metodi di spedizione, imposte o dati utente).ready_for_payment: lo stato da utilizzare dopo che l'utente ha aggiornato l'indirizzo di spedizione e hai calcolato le opzioni di spedizione e i totali, 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 convalidati tutti i dettagli dell'ordine.completed: lo stato finale restituito dopo aver elaborato correttamente il pagamento e aver effettuato l'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 versione UCP2026-04-08e successive.
Flusso di pagamento multi-articolo:
Google ora supporta più voci distinte in una singola 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 articoli 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 dell'API di pagamento nativo, inclusi i metodi di autenticazione supportati come le chiavi API e OAuth 2.0, consulta la guida Autenticazione e sicurezza.
Strumenti per sviluppatori
Per aiutarti con l'implementazione dell'API di pagamento nativo, puoi trovare le seguenti risorse nel repository GitHub del protocollo Universal Commerce:
- Repository GitHub 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 rispetto 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 dell'API REST di pagamento nativo. Le aziende che si integrano con Google devono soddisfare questi obiettivi 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} (Aggiorna) |
>= 95% | <= 1 secondo | <= 5 secondi |
POST /checkout-sessions/{id}/complete (Completa) |
>= 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 di pagamento e i dettagli dell'implementazione tecnica per la tua versione UCP: