Standardy protokołów

Interfejs API jest zgodny z zestawem standardów interfejsów API HTTP i obsługuje idempotentności, która usprawnia tworzenie i integrację społeczną.

Adresy URL hostowane przez Google

Dokumentacja poszczególnych metod hostowanych przez Google zawiera podstawowy adres URL, który zawiera nazwę metody i numer wersji głównej. Tworzony jest pełny adres URL dodając identyfikator konta integratora płatności wywołującego do na ich końcu. Możesz na przykład zapoznać się z dokumentacją hostowanej przez Google metody echo. określa adres URL:

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

Jeśli identyfikator konta integratora płatności wywołującego to INTEGRATOR_1, użytkownik dodałby że na końcu adresu URL w celu utworzenia:

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

Uwaga: strona dokumentacji punktów końcowych dla konkretnej metody aby otrzymać najdokładniejszy adres URL w danym przypadku.

Adresy URL hostowane przez partnera

Dokumentacja poszczególnych metod API hostowanych przez partnerów zawiera podstawowy adres URL, który zawiera nazwę metody i numer wersji głównej. Nie należy dodawać parametru Identyfikator konta integratora płatności (PIAID) w adresach URL, które hostujesz.

Piaskownica i środowiska produkcyjne

Google hostuje standardowe interfejsy API płatności zarówno w piaskownicy (do celów programistycznych do testowania) i produkcji. Żądania w środowisku piaskownicy Google nie skutkują żadną rzeczywistą odpowiedzialnością finansową. Piaskownica środowiska produkcyjne są całkowicie oddzielne i nie współdzielą kluczy ani informacje o transakcjach.

Google oczekuje, że Twoja piaskownica będzie stale dostępna, ponieważ będziemy korzystać z metody w środowisku piaskownicy, aby przetestować zmiany i nowe funkcje.

Ścieżka bazowa piaskownicy Google

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

Uwaga: jeśli Twoja integracja została już uruchomiona i wywołuje metodę gospodarzowi https://billpaynotification.sandbox.googleapis.com, możesz przejść do to zrobić. Nowe integracje powinny wywoływać adres „vgw.sandbox.google.com”. .

Ścieżka bazowa środowiska produkcyjnego Google

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

Uwaga: jeśli Twoja integracja została już uruchomiona i wywołuje metodę hosta https://billpaynotification.googleapis.com, możesz nadal to robić. Nowe integracje powinny wywoływać parametr „vgw.googleapis.com” .

W tym przewodniku będą używane produkcyjne punkty końcowe.

Typ treści i kodowanie

Ładunki wiadomości, które używają szyfrowania PGP, muszą używać typu treści application/octet-stream; charset=utf-8 Treści żądań PGP muszą być wysyłane przy użyciu kodowania base64url, zgodnie z definicją rfc4648 §5. Ładunki wiadomości korzystające z szyfrowania JWE muszą używać typu treści application/jose; charset=utf-8 Opcja kompaktowej serializacji obsługiwane przez JWE/JWS za kodowanie ostatecznej treści żądania.

Kody stanów HTTP

Standardowe interfejsy API płatności zostały zaprojektowane w taki sposób, by zwracać kod stanu HTTP 200. dla wszystkich żądań, które może przetworzyć serwer. Obejmuje to udanych i odrzuconych próśb z perspektywy firmy lub do logiki aplikacji. Żądania, których nie można przetworzyć, nie powinny skutkować kodu stanu HTTP 200, ponieważ reprezentują błąd występujący między Google a protokołem partnera. Zamiast tego odpowiedź interfejsu API powinna używać odpowiedniego stanu HTTP z opcjonalnym obiektem ErrorResponse.

Błędy HTTP i ich przyczyny
400	BAD REQUEST Klient podał nieprawidłowy argument. Ten kod błędu może też być zwracany, jeśli operacja została odrzucona, ponieważ system nie znajduje się w stanie wymaganym do wykonania operacji. Należy go użyć, jeśli kolejne próby żądania nie mogą się powieść do momentu osiągnięcia stanu systemu zostało już poprawione. Jeśli na przykład nie uda się zrealizować prośby o zwrot środków, odwołuje się do zapisu, który nie istnieje; ponawianie próby się nie powiedzie; dopóki nie przechwytuje się w systemie integratora. Uwaga: nie należy używać parametru BAD_REQUEST (400) w sytuacjach, gdy dostępny jest odpowiedni błąd aplikacji. Dla: Na przykład nieprawidłowe waluty powinny zwracać ACCOUNT_DOES_NOT_SUPPORT_CURRENCY z kodem 200, jeśli standardowa odpowiedź zawiera to pole lub wyliczenie.
401	UNAUTHORIZED Żądanie nie ma prawidłowych danych uwierzytelniających dla . Na przykład nieprawidłowe lub nieznane podpisy powinny zwraca kod 401.
403	FORBIDDEN / PERMISSION DENIED Wywołujący nie ma uprawnień do wykonania określonej operacji.
404	NOT FOUND Nie znaleziono żądanego elementu, takiego jak płatność lub użytkownik.
409	CONFLICT / ABORTED Operacja została przerwana, zwykle z powodu problemu równoczesności, takiego jak błędów kontroli sekwencera, przerwania transakcji itp.
412	PRECONDITION FAILED Tego kodu należy używać w sytuacjach, gdy jest używany klucz idempotentności ponownie użyte z innymi parametrami.
429	RESOURCE EXHAUSTED / TOO MANY REQUESTS Jeden zasób systemowy został wyczerpany.
499	CANCELLED Operacja została anulowana (zwykle przez osobę wywołującą).
500	INTERNAL ERROR Błędy wewnętrzne. Oznacza to, że pewne niezmienniki oczekiwane przez system bazowy została złamana.
501	UNIMPLEMENTED Operacja nie jest wdrożona, obsługiwana lub włączona w tej usłudze.
503	UNAVAILABLE Usługa jest obecnie niedostępna. Jest to najprawdopodobniej okres przejściowy, i można go poprawić, ponawiając próbę.
504	GATEWAY TIMEOUT / DEADLINE EXCEEDED Termin minął przed ukończeniem operacji. Operacje, które zmieni stan systemu, błąd może zostać zwrócony nawet wtedy, gdy operacja została ukończona. Przykład: udana odpowiedź z serwera mogło być opóźnione na tyle długo, że termin tracą ważność.

Idempotentność żądań

Idempotentność żądań to główna strategia używana w płatnościach standardowych. Interfejsy API używane do zapewniania, że interakcje systemowe między Google a partnerami są solidne i odporne na awarie. Żądania idempotentne to żądania, które mogą mogą być wysyłane wiele razy, ale mają taki sam skutek jak pojedyncze żądanie. Strategia ta ułatwia spójność wynikową między systemami, podejmuje kolejne próby, dzięki czemu nasze systemy mogą połączyć w określonym stanie zasobu.

Nasz interfejs API wykorzystuje idempotentność do:

• ograniczanie problemów związanych z uzgodnieniem przez udostępnianie wszystkich działań do wglądu co podlega audytom.
• zapobiegać biegom, zapewniając, że wiele identycznych żądań ten sam klient nie skutkuje innym stanem końcowym.
• minimalizacji stanu dzięki umożliwieniu rozumienia żądań w izolacji, dla poprawy wydajności i przepustowości dzięki usunięciu obciążenia serwera spowodowanego przechowywania danych.
• unikanie konieczności stosowania dodatkowych pól wskazujących, czy żądanie jest ponawiane.

.

Uwaga: wyniki błędów nie mogą być zapisywane w pamięci podręcznej ani zwracane idempotentnie. oraz do automatycznych ponownych prób w przypadku błędów musi być stosowana strategia wzrastającego czasu do ponowienia.

Przykłady

Przykład 1. Utrata połączenia przed otrzymaniem odpowiedzi

Scenariusz:

1. Google wysyła żądanie do integratora.
2. Serwer integratora otrzymuje to żądanie i przetwarza je.
3. Serwer Google traci zasilanie przed otrzymaniem odpowiedzi w kroku nr 2.
4. Zasilanie serwera Google zostanie przywrócone i zostanie wysłane to samo żądanie z tymi samymi parametrami (ten sam identyfikator i szczegóły żądania, ale zaktualizowane requestTimestamp) do serwera integratora.

Wynik:

W tym przypadku serwer integratora musi odpowiedzieć, wysyłając tę samą odpowiedź podaną w adresie Krok 2. Wszystkie parametry oprócz responseTimestamp są takie same. Efekt uboczny występuje tylko raz, w kroku 2. Krok 4 nie ma żadnych skutków ubocznych.

Przykład 2. Żądanie wysłane do serwera poddawanego konserwacji

Scenariusz:

1. Baza danych na serwerze integratora jest niedostępna z powodu konserwacji.
2. Google wysyła żądanie do integratora.
3. Integrator prawidłowo zwraca kod stanu UNAVAILABLE.
4. Serwer Google odbiera odpowiedź i planuje ponowienie próby.
5. Baza danych na serwerze integratora zostaje przywrócona online.
6. Google ponownie wysyła żądanie z kroku 2 (ten sam identyfikator i szczegóły prośby) ale zaktualizowano requestTimestamp). Pamiętaj, że identyfikatory obu żądań powinny być takie same.
7. Serwer integratora odbiera żądanie i zwraca kod stanu OK z pełną odpowiedzią.

Wynik:

W tym przypadku serwer integratora musi przetworzyć żądanie w kroku nr 7, a nie zwraca kod HTTP 503 (UNAVAILABLE). Zamiast tego serwer integratora powinien całkowicie przetworzy żądanie i zwróci OK z odpowiednim komunikatem. Pamiętaj, że choć system to UNAVAILABLE Google może wielokrotnie wysyłać żądania podobne do kroku 2. Każde takie żądanie powinno skutkować zwróceniem komunikatu podobnego do zwróconego w kroku 3. W końcu wystąpią kroki 6 i 7.

Przykład 3. Ponawiany komunikat nie pasuje do początkowego komunikatu z powodu błędu odzyskiwania

Scenariusz:

1. Google wysyła żądanie do integratora.
2. Serwer integratora otrzymuje to żądanie i przetwarza je.
3. Serwer Google traci zasilanie przed otrzymaniem odpowiedzi w kroku nr 2.
4. Zasilanie serwera Google zostanie przywrócone i nastąpi próba wysłania tego samego żądania ale niestety niektóre parametry są inne.

Wynik:

W tym przypadku serwer integratora powinien odpowiedzieć, przesyłając żądanie HTTP 412 (PRECONDITION FAILED), który informuje Google, że występuje w tym systemie.