Panoramica
Google Standard Payments supporta le forme di pagamento (forme di pagamento) basate su contanti come gli acquisti nei minimarket (ad esempio un 7-Eleven). A livello generale, un utente che vuole pagare dei prodotti genera un numero di riferimento tramite l'Integratore pagamenti. L'utente lo porta poi in un minimarket, un chiosco o una banca e paga il numero di riferimento.
|
|
|
Concetti e terminologia
Simboli e Convenzioni
Le parole chiave "DEVE", "NON DEVE" "OBBLIGATORIO", "SHALL" "NON DEVE" "DOVREBBE" "NON DOVREBBE" "CONSIGLIATO" "MAGGIO", e "OPTIONAL" in questi documenti devono essere interpretati come descritto in RFC 2119.
Timestamp
Tutti i timestamp sono rappresentati in millisecondi dall'epoca di Unix (1° gennaio 1970) in UTC.
Ad esempio:
- 23 aprile 2019 20:23:25 GMT = 1556051005000 millisecondi
- 16 agosto 2018 12:28:35 GMT = 1534422515000 millisecondi
Importi
I valori monetari in questa API sono nel formato "micro", uno standard offerto da Google. I micro sono un formato a precisione fissa basato su numeri interi. Per rappresentare un valore monetario in micro, moltiplica il valore della valuta standard per 1.000.000.
Ad esempio:
- 1,23$= 1230.000 micro USD
- 0,01$= 10.000 micro USD
Idempotenza
Tutte le chiamate al metodo all'interno di questa API devono avere un comportamento idempotente. Google riproverà sporadicamente le richieste per garantire che le transazioni siano nello stesso stato su entrambe le parti. Gli integratori non devono tentare di rielaborare richieste già elaborate correttamente. Dovrebbe invece essere segnalata la risposta per l'elaborazione riuscita. Tutti i metodi hanno un elemento RequestHeader comune che contiene un requestId. Questo requestId è la chiave di idempotenza per tutte le chiamate.
Qualsiasi risposta senza terminale (non HTTP 200-success) non deve essere elaborata in modo idempotente. Di conseguenza, una richiesta che in precedenza ha ricevuto un 400 (richiesta errata/precondizione non riuscita), quando viene chiamata una seconda volta, non deve restituire idempotentemente 400 e deve essere rivalutata. Alla nuova valutazione, potrebbe restituire un errore 400 o essere elaborato correttamente.
Per ulteriori informazioni sull'idempotenza, consulta questa guida dettagliata.
Integratore
Una società che utilizza la piattaforma di pagamento di Google per la propria attività. Potrebbe trattarsi di un'attività interna, ad esempio YouTube o AdWords, o di un'attività di terze parti che vuole integrare il proprio servizio in modo che funzioni con l'ecosistema di Google.
forma di pagamento
Forma di pagamento. È più generico di uno strumento. Visa, MasterCard e PayPal sono tutte forme di forma di pagamento.
Strumento
Un'istanza particolare di una forma di pagamento da parte di un cliente specifico. ad esempio la carta di credito o l'account PayPal di un utente. Anche una forma di pagamento tokenizzata per un determinato cliente è uno strumento, in quanto è un'istanza di una forma di pagamento per il cliente in questione, memorizzata in modo sicuro nel nostro sistema.
Token
La rappresentazione sul sistema di Google del metodo di pagamento di uno specifico utente. Poiché contiene tutte le informazioni necessarie per effettuare un acquisto, anche un token è uno strumento. Potrebbero essere incluse informazioni quali il numero di conto bancario di un utente presso il proprio integratore.
Flussi chiave
Google utilizza due flussi chiave per creare e pagare questi numeri di riferimento:
- Genera flusso con numeri di riferimento.
- Flusso dei numeri di riferimento dei pagamenti.
In seguito, la riconciliazione e la liquidazione degli acquisti risultanti saranno gestite dal flusso dei versamenti.
Il diagramma seguente illustra ciascuno di questi flussi.
Panoramica della forma di pagamento in contanti
I primi due flussi sono descritti in modo più dettagliato nelle sezioni seguenti. Per saperne di più su questo flusso, consulta la pagina Flusso di versamento.
Genera numero di riferimento
Lo scopo del flusso di generazione del numero di riferimento è creare e scambiare un identificatore (numero di riferimento) che sia Google sia l'integratore possono utilizzare per identificare un acquisto. L'utente può quindi utilizzare questo numero di riferimento in un minimarket, un chiosco o una banca per completare l'acquisto. Questo identificatore viene generato dall'integratore su richiesta di Google chiamando il metodo generateReferenceNumber. La richiesta di generazione del numero di riferimento include un importo e una descrizione della transazione.
Il seguente diagramma illustra come viene generato e inviato un numero di riferimento al cliente con le istruzioni.
Genera flusso di numeri di riferimento
Ecco un elenco degli oggetti e di ciò che rappresentano:
- Utente: la persona che vuole pagare un prodotto utilizzando questa forma di pagamento.
- UI di Google: l'interfaccia in cui l'utente effettua l'acquisto. tramite il web o un'app.
- Server di Google: il server di backend di Google che richiede la generazione del numero di riferimento e crea le istruzioni di pagamento per l'utente.
- Server integratore di pagamenti: il server di backend dell'integratore di pagamenti che tiene traccia dei dettagli sui pagamenti e genera il numero di riferimento.
Questo flusso inizia con l'utente che desidera utilizzare questa forma di pagamento in contanti.
- L'utente accede all'interfaccia utente di Google che invia una richiesta relativa a un numero di riferimento.
- L'interfaccia utente di Google invia un messaggio al server di Google che informa che è necessario un numero di riferimento (
getReferenceNumber). - Il server di Google chiede al server Payment Integrator di generare un numero di riferimento (
generateReferenceNumber). - Il server integratore di pagamenti genera e invia il numero di riferimento al server di Google.
- Il server di Google crea istruzioni per il pagamento da utilizzare insieme al numero di riferimento. Quindi invia queste informazioni all'interfaccia utente di Google.
- L'interfaccia utente di Google invia queste istruzioni e il numero di riferimento all'utente.
Note sui numeri di riferimento
I numeri di riferimento possono essere pagati una sola volta e possono essere annullati tramite il flusso dei numeri di riferimento per l'annullamento. Inoltre, i numeri di riferimento devono essere alfanumerici e supportare più formati di visualizzazione.
Oltre a visualizzare il numero di riferimento, le UI di Google possono facoltativamente rappresentare il numero di riferimento nel formato codice 128 (per codice a barre). Su richiesta possono essere supportati altri formati di codici a barre.
Numero di riferimento pagamenti
L'utente utilizzerà questo numero di riferimento in un minimarket, un chiosco o una banca per identificare l'acquisto che intende pagare. L'integratore deve chiedere all'utente di confermare l'acquisto pagato mostrando l'importo, la data e la descrizione della transazione prima del pagamento.
Una volta che l'utente sceglie di pagare, deve pagare l'intero importo e pagare una sola volta. Questa API non supporta pagamenti in eccesso o in difetto su un unico numero di riferimento. Non sono inoltre supportati più pagamenti verso un unico numero di riferimento.
Una volta che l'utente paga, l'integratore deve immediatamente comunicare a Google che questo numero di riferimento è stato pagato tramite il metodo referenceNumberPaidNotification. Chiamando questo metodo entro pochi secondi dal momento in cui l'utente paga fisicamente, l'integratore consente all'utente di ricevere rapidamente i prodotti. Questa chiamata può essere aggiunta a una coda se la rete non è disponibile.
Una volta pagato, il numero di riferimento e l'importo verranno inclusi nella distinta di versamento inviata entro T+2 giorni.
Ecco un diagramma di sequenza che illustra il pagamento di un numero di riferimento.
Flusso del numero di riferimento pagamenti
Gli oggetti nel diagramma rappresentano quanto segue:
- Utente: la persona che vuole pagare un prodotto utilizzando questa forma di pagamento.
- Minimarket: il luogo in cui l'utente effettua il pagamento utilizzando il numero di riferimento e le istruzioni fornite, ad esempio un minimarket.
- Server integratore di pagamenti: il server di backend dell'integratore di pagamenti che tiene traccia dei dettagli sui pagamenti.
- Server di Google: il server di backend di Google che richiede la generazione del numero di riferimento e crea le istruzioni di pagamento per l'utente.
Questo flusso inizia con l'utente che si reca in un minimarket per effettuare un pagamento in base alle istruzioni fornite.
- L'utente si reca in un minimarket per effettuare il pagamento.
- Al termine della transazione, il minimarket avvisa l'integratore dei pagamenti del pagamento.
- Il server integratore di pagamenti invia un messaggio di operazione riuscita al minimarket.
- Il minimarket comunica all'Utente che la transazione è andata a buon fine e i prodotti verranno consegnati a breve all'Utente.
- Il server integratore di pagamenti invia un messaggio al server di Google che informa che il numero di riferimento è stato pagato (
referenceNumberPaidNotification). Questo passaggio non deve bloccare il passaggio 4. - Il server di Google risponde con un messaggio di riuscita al server Payment Integrator.
Annulla numero di riferimento
I numeri di riferimento possono essere annullati da Google. Se Google annulla un numero di riferimento, verrà chiamato il metodo cancelReferenceNumber. Se questa chiamata viene restituita, non è possibile pagare quel numero di riferimento e l'integratore deve rifiutare il pagamento per questo numero. Se questa chiamata andrà a buon fine, tutte le chiamate future al referenceNumberPaidNotification non andranno a buon fine.
Se la procedura di pagamento è già iniziata, ad esempio se l'utente ha inserito il proprio numero di riferimento in un kiosk ma non ha ancora pagato, l'integratore deve restituire un codice di risposta HTTP 423 con ErrorResponse contenente USER_ACTION_IN_PROGRESS.
Successivo: Flusso di versamento