Standardy protokołów

Interfejs API jest zgodny z zestawem standardów interfejsów API HTTP i obsługuje mechanizm idempotentności, który ułatwia ścisłą integrację.

Adresy URL hostowane przez Google

Dokumentacja poszczególnych metod hostowanych przez Google zawiera podstawowy adres URL, który obejmuje nazwę metody i numer wersji głównej. Pełny adres URL tworzy się, dodając na końcu identyfikator konta integratora płatności elementu wywołującego. Na przykład dokumentacja hostowanej przez Google metody echa zawiera adres URL:

https://vgw.googleapis.com/gsp/refundable-one-time-payment-code-v1/echo

Jeśli identyfikator konta integratora płatności użytkownika wywołującego to INTEGRATOR_1, należy go dodać na końcu adresu URL, by otrzymać:

https://vgw.googleapis.com/gsp/refundable-one-time-payment-code-v1/echo/INTEGRATOR_1

Uwaga: strona z dokumentacją punktu końcowego w przypadku konkretnej metody, którą wdrażasz, będzie zawierać najbardziej dokładny adres URL Twojego zgłoszenia.

Adresy URL hostowane przez partnera

Dokumentacja poszczególnych metod API hostowanych przez partnerów zawiera podstawowy adres URL, który obejmuje nazwę metody i numer wersji głównej. Partner nie powinien dołączać identyfikatora konta integratora płatności (PIAID) w adresach URL, które hostuje.

Piaskownica i środowiska produkcyjne

Google hostuje interfejs API kodu płatności jednorazowej zarówno w piaskownicy (w celach dotyczących programowania i testowania), jak i w środowisku produkcyjnym. Żądania w środowisku piaskownicy Google nie skutkują żadną rzeczywistą odpowiedzialnością finansową. Środowisko piaskownicy i środowisko produkcyjne są całkowicie oddzielone i nie współużytkują kluczy ani danych dotyczących transakcji.

Google oczekuje, że Twoja piaskownica będzie stale dostępna, ponieważ będziemy jej używać, by najpierw przetestować zmiany i nowe funkcje.

Ścieżka bazowa piaskownicy Google

https://vgw.sandbox.google.com/gsp/

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

Ścieżka bazowa środowiska produkcyjnego Google

https://vgw.googleapis.com/gsp/

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

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

Typ treści i kodowanie

Ładunki komunikatów, w których jest używane szyfrowanie PGP, muszą korzystać z typu treści application/octet-stream; charset=utf-8. Ładunki komunikatów, w których jest używane szyfrowanie JWE, muszą korzystać z typu treści application/jose; charset=utf-8. Treści żądań muszą być wysyłane przy użyciu kodowania base64url, zgodnie z definicją w dokumencie rfc4648 §5.

Kody stanów HTTP

Interfejsy API kodu płatności jednorazowej zostały zaprojektowane w taki sposób, aby zwracać kod stanu HTTP 200 w przypadku wszystkich żądań, które może przetworzyć serwer. Obejmuje to zarówno udane, jak i odrzucone żądania z punktu widzenia logiki biznesowej lub aplikacji. Żądania, których nie można przetworzyć, nie powinny zwracać kodu stanu HTTP 200, ponieważ reprezentują błąd występujący między Google a partnerem. Zamiast tego odpowiedź interfejsu API powinna używać odpowiednich kodów stanu HTTP przedstawionych poniżej, 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 jej wykonania. Należy go użyć, jeśli kolejne próby żądania nie mogą się powieść, dopóki stan systemu nie zostanie bezpośrednio poprawiony. Jeśli na przykład żądanie zwrotu środków kończy się niepowodzeniem, ponieważ odwołuje się do nieistniejącego zapisu, ponowne próby nie powiodą się, dopóki zapis nie pojawi się w systemie integratora. Uwaga: kodu BAD_REQUEST (400) nie należy używać w sytuacjach, gdy dostępny jest odpowiedni błąd aplikacji. Na przykład nieprawidłowe waluty powinny zwracać błąd 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 tej operacji. Kod 401 powinien być na przykład zwracany w przypadku nieprawidłowych lub nieznanych podpisów.
403	FORBIDDEN / PERMISSION DENIED Element 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, najczęściej z powodu problemu równoczesności, np. w przypadku nieudanych kontroli sekwencera, przerwanych transakcji itp.
412	PRECONDITION FAILED Tego kodu należy używać w sytuacjach, gdy klucz idempotentności jest używany ponownie z innymi parametrami.
429	RESOURCE EXHAUSTED / TOO MANY REQUESTS Jeden z zasobów systemowych został wyczerpany.
499	CANCELLED Operacja została anulowana (zwykle przez element wywołujący).
500	INTERNAL ERROR Błędy wewnętrzne. Oznacza to, że pewne niezmienniki oczekiwane przez system bazowy zostały uszkodzone.
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 najczęściej stan przejściowy, który można rozwiązać, ponawiając próbę.
504	GATEWAY TIMEOUT / DEADLINE EXCEEDED Termin upłynął przed wykonaniem operacji. W przypadku operacji, które zmieniają stan systemu, ten błąd może zostać zwrócony nawet wówczas, gdy operacja zakończyła się pomyślnie. Na przykład pomyślna odpowiedź serwera mogła być tak opóźniona, że termin upłynął.

Idempotentność żądań

Idempotentność żądań to podstawowa strategia używana w interfejsach API kodu płatności jednorazowej stosowana w celu zapewnienia niezawodności i odporności na awarie systemowych interakcji między Google a partnerami. Żądania idempotentne to żądania, które można wysyłać wielokrotnie, ale ich efekt jest taki sam jak żądania pojedynczego. Strategia ta ułatwia zachowanie spójności wynikowej między systemami przez zapewnienie bezpieczeństwa wykonywania ponownych prób, co pozwala naszym systemom osiągać zgodność co do stanu zasobu.

Nasz interfejs API wykorzystuje idempotentność do:

• ograniczania problemów związanych z uzgadnianiem dzięki ułatwianiu śledzenia i kontrolowania wszystkich działań;
• zapobiegania sytuacjom wyścigu dzięki osiągnięciu tego, że wiele identycznych żądań od tego samego klienta nie prowadzi do różnych stanów końcowych;
• minimalizacji stanu dzięki umożliwieniu rozumienia żądań w izolacji, czego efektem jest większa wydajność i przepustowość ze względu na mniejsze obciążenie serwera związane z przechowywaniem danych;
• unikania konieczności stosowania dodatkowych pól wskazujących, czy żądanie jest ponowną próbą.

Uwaga:wyniki z błędami nie mogą być zapisywane w pamięci podręcznej ani zwracane idempotentnie. Natomiast w automatycznych ponownych próbach 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 zapisu transakcji do integratora.
2. Serwer integratora odbiera to żądanie i przetwarza je.
3. Serwer Google traci zasilanie przed otrzymaniem odpowiedzi w kroku nr 2.
4. Zasilanie serwera Google zostaje przywrócone i to samo żądanie zapisu transakcji jest wysyłane z tymi samymi parametrami (taki sam identyfikator i szczegóły żądania, ale zaktualizowany element requestTimestamp) do serwera integratora.

Wynik:

W tym przypadku serwer integratora musi udzielić takiej samej odpowiedzi jak w kroku nr 2, ponieważ wszystkie parametry z wyjątkiem responseTimestamp są takie same. Konto użytkownika zostaje obciążone tylko raz, w kroku nr 2. Zdarzenie z kroku nr 4 nie ma żadnych skutków finansowych dla użytkownika.

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

Scenariusz:

1. Baza danych na serwerze integratora nie działa 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 nr 2 (taki sam identyfikator i szczegóły żądania, ale zaktualizowany element requestTimestamp). Zwróć uwagę, że identyfikatory obu żądań muszą być takie same.
7. Serwer integratora otrzymuje żądanie i zwraca kod stanu OK wraz z pełną odpowiedzią.

Wynik:

W tym przypadku serwer integratora musi przetworzyć żądanie w kroku nr 7 i nie może zwrócić kodu HTTP 503 (UNAVAILABLE). Zamiast tego powinien do końca przetworzyć żądanie i zwrócić kod OK z odpowiednim komunikatem. Zwróć uwagę, że gdy system jest w stanie UNAVAILABLE, Google może wielokrotnie wysłać żądania podobne do wysłanego w kroku nr 2. Każde takie żądanie powinno skutkować zwróceniem komunikatu podobnego do zwróconego w kroku nr 3. W konsekwencji 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 odbiera to żądanie i przetwarza je.
3. Serwer Google traci zasilanie przed otrzymaniem odpowiedzi w kroku nr 2.
4. Zasilanie serwera Google zostaje przywrócone i podejmuje on próbę wysłania tego samego żądania, ale niestety niektóre parametry są inne.

Wynik:

W tym przypadku serwer integratora powinien udzielić odpowiedzi z kodem błędu HTTP 412 (PRECONDITION FAILED), który informuje Google, że w tym systemie występuje błąd.