Standard di protocollo

L'API segue una serie di standard API HTTP e supporta l'idempotenza per facilitare un'integrazione più solida.

URL ospitati su Google

La documentazione per ogni metodo ospitato da Google fornisce un URL di base che include il nome del metodo e il numero di versione principale. L'URL completo viene creato aggiungendo l'ID account di integrazione pagamenti del chiamante alla fine. Ad esempio, la documentazione per il metodo echo ospitato da Google specifica l'URL:

https://vgw.googleapis.com/secure-serving/gsp/v1/echo

Se l'ID account dell'integratore dei pagamenti del chiamante è INTEGRATOR_1, lo aggiungerebbe alla fine dell'URL per formare:

https://vgw.googleapis.com/secure-serving/gsp/v1/echo/INTEGRATOR_1

Nota: la pagina della documentazione dell'endpoint relativa al metodo specifico che stai implementando avrà l'URL più preciso per la tua richiesta.

URL ospitati dal partner

La documentazione per ciascun metodo dell'API ospitata dal partner fornisce un URL di base che include il nome del metodo e il numero di versione principale. Non devi includere l'ID account per l'integrazione dei pagamenti (PIAID) negli URL ospitati.

Ambienti sandbox e di produzione

Google ospita le API Standard Payments sia in sandbox (per scopi di sviluppo e test) che in produzione. Le richieste nell'ambiente sandbox di Google non comportano alcuna responsabilità finanziaria reale. Gli ambienti sandbox e di produzione sono completamente separati e non condividono chiavi o informazioni sulle transazioni.

Google si aspetta che la sandbox sia costantemente disponibile poiché la utilizzeremo per testare prima le modifiche e le nuove funzionalità.

Percorso di base della sandbox di Google

https://vgw.sandbox.google.com/secure-serving/gsp/

Nota: se l'integrazione è già stata avviata e chiama l'host https://billpaynotification.sandbox.googleapis.com, puoi continuare a farlo. Le nuove integrazioni devono chiamare l'host "vgw.sandbox.google.com".

Percorso di base di produzione di Google

https://vgw.googleapis.com/secure-serving/gsp/

Nota: se l'integrazione è già stata avviata e chiama l'host https://billpaynotification.googleapis.com, puoi continuare a farlo. Le nuove integrazioni dovrebbero chiamare l'host "vgw.googleapis.com".

Questa guida utilizzerà gli endpoint di produzione.

Tipo di contenuti e codifica

I payload dei messaggi che utilizzano la crittografia PGP devono utilizzare il tipo di contenuti application/octet-stream; charset=utf-8. I corpi delle richieste PGP devono essere inviati utilizzando la codifica base64url, come definito in rfc4648 §5. I payload dei messaggi che utilizzano la crittografia JWE devono utilizzare il tipo di contenuto application/jose; charset=utf-8. L'opzione di serializzazione compatta supportata da JWE/JWS gestisce la codifica per il corpo della richiesta finale.

Codici di stato HTTP

Le API standard di Payments sono progettate per restituire un codice di stato HTTP 200 per tutte le richieste che possono essere elaborate dal server. Ciò include le richieste andate a buon fine e quelle rifiutate dal punto di vista della logica di business o applicativa. Le richieste che non possono essere elaborate non devono restituire un codice di stato HTTP 200 poiché rappresentano un errore tra Google e il partner. La risposta dell'API deve invece utilizzare i codici di stato HTTP appropriati riportati di seguito con un oggetto ErrorResponse facoltativo.

Errori HTTP e motivi
400	BAD REQUEST Il client ha specificato un argomento non valido. Questo valore può essere restituito anche se l'operazione è stata rifiutata perché il sistema non è nello stato richiesto per l'esecuzione dell'operazione. Utilizza questa opzione se i nuovi tentativi della richiesta non possono andare a buon fine finché lo stato del sistema non viene corretto esplicitamente. Ad esempio, se una richiesta di rimborso non va a buon fine perché fa riferimento a un'acquisizione inesistente, un nuovo tentativo non avrà esito positivo finché l'acquisizione non sarà esistente nel sistema degli integratori. Nota: non utilizzare BAD_REQUEST (400) quando è disponibile un errore dell'applicazione appropriato. Ad esempio, le valute errate dovrebbero restituire ACCOUNT_DOES_NOT_SUPPORT_CURRENCY con codice 200 se la risposta standard include questo campo o enum.
401	UNAUTHORIZED La richiesta non dispone di credenziali di autenticazione valide per l'operazione. Ad esempio, le firme non valide o sconosciute devono restituire un codice 401.
403	FORBIDDEN / PERMISSION DENIED Il chiamante non dispone dell'autorizzazione per eseguire l'operazione specificata.
404	NOT FOUND Alcune entità richieste, come il pagamento o l'utente, non sono state trovate.
409	CONFLICT / ABORTED L'operazione è stata interrotta, in genere a causa di un problema di contemporaneità come errori del controllo del sequenziatore, interruzioni delle transazioni e così via.
412	PRECONDITION FAILED Questo codice deve essere utilizzato in situazioni in cui una chiave di idempotenza viene riutilizzata con parametri diversi.
429	RESOURCE EXHAUSTED / TOO MANY REQUESTS Alcune risorse di sistema sono esaurite.
499	CANCELLED L'operazione è stata annullata (in genere dal chiamante).
500	INTERNAL ERROR Errori interni. Ciò significa che alcuni invarianti previsti dal sistema sottostante sono stati danneggiati.
501	UNIMPLEMENTED L'operazione non è implementata, supportata o abilitata in questo servizio.
503	UNAVAILABLE Il servizio non è al momento disponibile. Molto probabilmente si tratta di una condizione temporanea e può essere corretta riprovando.
504	GATEWAY TIMEOUT / DEADLINE EXCEEDED Scadenza scaduta prima del completamento dell'operazione. Per le operazioni che cambiano lo stato del sistema, questo errore può essere restituito anche se l'operazione è stata completata correttamente. Ad esempio, una risposta corretta da un server potrebbe essere ritardata abbastanza a lungo da far scadere la scadenza.

Richiedi idempotenza

L'idempotenza delle richieste è una strategia centrale utilizzata nelle API dei pagamenti standard per garantire che le interazioni di sistema tra Google e i partner siano solide e a tolleranza di errore. Le richieste idempotenti sono richieste che potenzialmente possono essere inviate più volte, ma hanno lo stesso effetto di una singola richiesta. Questa strategia facilita la coerenza finale tra i sistemi rendendo sicuri i tentativi e consentendo ai nostri sistemi di coalizzare un accordo sullo stato della risorsa.

La nostra API sfrutta l'idempotenza per:

• ridurre i problemi di riconciliazione rendendo tutte le azioni facilmente tracciabili e verificabili.
• prevenire le condizioni di gara garantendo che più richieste identiche dello stesso client non causino uno stato finale diverso.
• ridurre al minimo lo stato consentendo di comprendere le richieste separatamente, consentendo di migliorare le prestazioni e la velocità effettiva rimuovendo il carico del server causato dalla conservazione dei dati.
• evita di dover compilare campi aggiuntivi per indicare se una richiesta è un nuovo tentativo

Nota: i risultati degli errori non devono mai essere memorizzati nella cache o restituiti in modo idempotente. Inoltre, i nuovi tentativi automatici per gli errori devono utilizzare una strategia di backoff esponenziale.

Esempi

Esempio 1: connettività persa prima della ricezione della risposta

Scenario:

1. Google invia una richiesta all'integratore.
2. Il server di integrazione riceve questa richiesta e la elabora correttamente.
3. Il server di Google si disconnette prima di ricevere la risposta nel passaggio 2.
4. L'alimentazione del server di Google viene ripristinata e la stessa richiesta viene inviata con tutti gli stessi parametri (lo stesso ID richiesta e dettagli della richiesta ma aggiornati requestTimestamp) al server dell'integratore.

Risultato:

In questo caso, il server di integrazione deve rispondere con la stessa risposta fornita al passaggio 2, poiché tutti i parametri, tranne responseTimestamp, sono gli stessi. L'effetto collaterale si verifica una sola volta, al passaggio 2. Il passaggio 4 non ha effetti collaterali.

Esempio 2: richiesta inviata a un server in fase di manutenzione

Scenario:

1. Il database del server di integrazione non è disponibile per manutenzione.
2. Google invia una richiesta all'integratore.
3. L'integratore restituisce correttamente il codice di stato UNAVAILABLE.
4. Il server di Google riceve la risposta e pianifica un nuovo tentativo.
5. Il database del server di integrazione torna online.
6. Google invia di nuovo la richiesta del passaggio 2 (stesso ID richiesta e stesso dettagli della richiesta, ma aggiornato con requestTimestamp). Tieni presente che gli ID richiesta per entrambe le richieste devono essere uguali.
7. Il server di integrazione riceve la richiesta e restituisce un codice di stato OK insieme alla risposta completa.

Risultato:

In questo caso, il server di integrazione deve elaborare la richiesta nel passaggio 7 e non restituire HTTP 503 (UNAVAILABLE). Al contrario, il server di integrazione deve elaborare completamente la richiesta e restituire OK con il messaggio appropriato. Tieni presente che anche se il sistema è UNAVAILABLE, Google potrebbe effettuare richieste ripetute simili al passaggio 2. Ogni richiesta dovrebbe generare un messaggio simile al passaggio 3. Alla fine verranno eseguiti i passaggi 6 e 7.

Esempio 3: il messaggio ripetuto non corrisponde al messaggio iniziale a causa di un errore di recupero

Scenario:

1. Google invia una richiesta all'integratore.
2. Il server di integrazione riceve questa richiesta e la elabora correttamente.
3. Il server di Google si disconnette prima di ricevere la risposta nel passaggio 2.
4. La potenza del server di Google viene ripristinata e tenta di inviare la stessa richiesta, ma purtroppo alcuni parametri sono diversi.

Risultato:

In questo caso, il server di integrazione deve rispondere con un codice di errore HTTP 412 (PRECONDITION FAILED) che indica a Google la presenza di un errore nel sistema.