Panoramica
Google Standard Payments supporta forme di pagamento (FOP) basate su contanti, come gli acquisti nei minimarket (ad esempio un 7-Eleven). A livello generale, un utente che vuole pagare per dei beni genera un numero di riferimento tramite l'integratore dei pagamenti. L'utente porta poi questo numero di riferimento a un minimarket, un chiosco o una banca e paga questo numero.
|
|
|
Concetti e terminologia
Simboli e convenzioni
Le parole chiave "DEVE", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY" e "OPTIONAL" in questi documenti devono essere interpretate come descritto nel documento RFC 2119.
Timestamp
Tutti i timestamp sono rappresentati in millisecondi dall'epoca Unix (1 gennaio 1970) nel fuso orario 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 in un formato chiamato "micros", uno standard di 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 USD = 1230000 micro USD
- 0,01$= 10.000 micro USD
Idempotenza
Tutte le chiamate al metodo all'interno di questa API devono avere un comportamento idempotente. sporadicamente Google riproverà le richieste per garantire che le transazioni siano nello stesso stato su entrambi i lati. Gli integratori non devono tentare di rielaborare le richieste già elaborate correttamente. La risposta per l'elaborazione corretta dovrebbe essere invece registrata. Tutti i metodi hanno un RequestHeader comune che contiene un requestId. Questo requestId è la chiave di idempotenza per tutte le chiamate.
Qualsiasi risposta non terminale (un errore HTTP 200 con esito positivo) non deve essere elaborata in modo idempotente. Pertanto, una richiesta che in precedenza riceveva un valore 400 (precondizione errata/non valida), quando chiamata una seconda volta, non deve restituire idempotentemente 400, deve essere rivalutata. Al momento della nuova valutazione, potrebbe restituire un valore 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à. Può essere un'azienda interna (1P), come YouTube o AdWords, o anche un'attività esterna (3P) che vuole integrare il proprio servizio per funzionare con l'ecosistema di Google.
FOP
Forma di pagamento. Questa procedura è più generica rispetto a uno strumento. Visa, MasterCard e PayPal sono tutte forme di pagamento.
Strumento
Un caso particolare di una forma di pagamento da parte di un cliente specifico. ad esempio la carta di credito di un utente o l'account PayPal. Anche una forma di pagamento tokenizzata per un determinato cliente è uno strumento, perché è un'istanza di una forma di pagamento per quel cliente, memorizzata in modo sicuro nel nostro sistema.
Token
Una rappresentazione, sul sistema di Google, del metodo di pagamento di un utente specifico. Poiché contiene tutte le informazioni necessarie per effettuare un acquisto, anche il token è uno strumento. Ciò può includere informazioni quali il numero di account che un utente ha presso il suo integratore.
Flussi principali
Google utilizza due flussi chiave per creare e pagare questi numeri di riferimento:
- Genera flusso del numero di riferimento.
- Flusso del numero di riferimento sul pagamento.
In seguito, la riconciliazione e la liquidazione degli acquisti risultanti vengono gestite dal flusso di pagamento.
Il diagramma seguente illustra ciascuno di questi flussi.
Panoramica della forma di pagamento contante
I primi due flussi sono descritti in maggiore dettaglio nelle sezioni seguenti. Per saperne di più, consulta la pagina Flusso di pagamento.
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 che l'integratore possono utilizzare per identificare un acquisto. L'utente può quindi utilizzare questo numero di riferimento presso 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 un numero di riferimento viene generato e inviato al cliente con le istruzioni.
Genera flusso del numero di riferimento
Ecco un elenco degli oggetti e di ciò che rappresentano:
- Utente: si tratta della persona che desidera effettuare un pagamento utilizzando questa forma di pagamento.
- UI di Google: si tratta dell'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 dell'integrazione dei pagamenti: il server di backend dell'integratore dei pagamenti che tiene traccia dei dettagli di pagamento e genera il numero di riferimento.
Questo flusso inizia con l'utente che vuole utilizzare questa forma di pagamento in contanti.
- L'utente accede all'interfaccia utente di Google che invia una richiesta per un numero di riferimento.
- La UI di Google invia un messaggio al server di Google in cui comunica che ha bisogno di un numero di riferimento (
getReferenceNumber). - Il server di Google chiede al server dell'integrazione dei pagamenti di generare un numero di riferimento (
generateReferenceNumber). - Il server dell'integrazione dei pagamenti genera e invia il numero di riferimento al server di Google.
- Il server di Google crea le istruzioni di pagamento insieme al numero di riferimento. Poi 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 di annullamento del numero di riferimento. Inoltre, i numeri di riferimento devono essere alfanumerici e devono 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 (formato di codici a barre). Altri formati di codici a barre sono supportati su richiesta.
Numero di riferimento del pagamento
L'utente utilizzerà questo numero di riferimento presso un minimarket, un chiosco o una banca per identificare l'acquisto che vuole pagare. L'integratore deve chiedere all'utente di confermare che l'acquisto viene pagato mostrando l'importo, la data e la descrizione della transazione prima del pagamento.
Quando l'utente sceglie di pagare, deve pagare l'intero importo e solo una volta. Questa API non supporta i pagamenti in eccesso o in difetto per un unico numero di riferimento. Non sono inoltre supportati più pagamenti a un unico numero di riferimento.
Una volta che l'utente paga, l'integratore deve immediatamente informare Google che questo numero di riferimento è stato pagato tramite il metodo referenceNumberPaidNotification. Richiamando questo metodo entro pochi secondi dall'utente che 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 effettuato il pagamento, il numero di riferimento e l'importo saranno inclusi nell'estratto conto inviato il T+2 giorni.
Di seguito è riportato un diagramma di sequenza che illustra il pagamento di un numero di riferimento.
Flusso del numero di riferimento del pagamento
Gli oggetti nel diagramma rappresentano quanto segue:
- Utente: si tratta della persona che desidera effettuare un pagamento utilizzando questa forma di pagamento.
- Minimarket: il luogo in cui l'utente effettua il pagamento utilizzando il numero di riferimento e le istruzioni, ad esempio un minimarket.
- Server dell'integrazione dei pagamenti: il server di backend dell'integratore dei pagamenti che tiene traccia dei dettagli di pagamento.
- 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 secondo le istruzioni che gli sono state fornite.
- L'utente si reca in un minimarket per effettuare un pagamento.
- Una volta completata la transazione, il minimarket invia una notifica al pagamento all'integratore dei pagamenti.
- Il server di integrazione dei pagamenti invia un messaggio di successo al minimarket.
- Il minimarket comunica che la transazione è stata un successo per l'utente e che la merce verrà consegnata a breve all'utente.
- Il server dell'integrazione dei pagamenti invia un messaggio al server di Google per comunicare 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 esito positivo al server di integrazione dei pagamenti.
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 la chiamata viene restituita, il numero di riferimento non è valido e l'integratore deve rifiutare il pagamento per questo numero. Se questa chiamata ha esito positivo, tutte le chiamate future al referenceNumberPaidNotification non andranno a buon fine.
Se il processo di pagamento è già iniziato, 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 pagamento