Autoryzacja i wymagania techniczne

W tym rozdziale znajdziesz informacje dotyczące autoryzacji w komunikacji z InPost Pay oraz konfiguracji konta Merchanta i generowania dostępów (client_id i client_secret).

Na tej stronie:

Autoryzacja

Do uwierzytelniania komunikacji klienta z InPost Pay (Basket App) wykorzystany jest standard OAuth 2.0. W przypadku komunikacji service to service – bez kontekstu zalogowanego użytkownika wykorzystany jest client_credentials flow a OAuth (https://www.oauth.com/oauth2-servers/access-tokens/client-credentials/).

• Merchant otrzymuje swój client_id i client_secret

• Pobiera access token

• Podpisuje każdy request. Access token należy przekazać w nagłówku Authorization: Bearer W-TYM-MIEJSCU-NALEZY-UMIESCIC-TOKEN

• Serwer zasobów weryfikuje token i identyfikuje klienta

Token endpoint jest stały i może być parametrem konfiguracyjnym po stronie klienta:

• środowisko produkcyjne
  https://login.inpost.pl/auth/realms/external/protocol/openid-connect/token

• środowisko sandbox
  https://sandbox-login.inpost.pl/auth/realms/external/protocol/openid-connect/token

Pobranie tokenu

Request

Response

Przykład implementacji w PHP

• Tworzymy interface serwisu, który będzie odpowiedzialny za pobranie bearer access token.

  <?php declare(strict_types=1); namespace Iteo\InpostPayClient\Client; use Iteo\InpostPayClient\SDK\Core\Exceptions\InpostPayEndpointException; /** * Interface used for creating bearer token, needed to communication with Inpost Pay. */ interface InpostPayBearerServiceInterface { /** * Method that creating bearer access token for given merchant credentials. * * @return string Bearer access token * * @throws InpostPayEndpointException */ public function getBearerToken(): string; }

• Tworzymy exception, który będziemy zwracali w przypadku niepowodzenia pobrania tokenu.

  <?php declare(strict_types=1); namespace Iteo\InpostPayClient\SDK\Core\Exceptions; class InpostPayEndpointException extends \Exception { final public function __construct(string $message = '', int $code = 0, \Throwable $previous = null) { parent::__construct($message, $code, $previous); } public static function createClientException(\Throwable $throwable): self { return new static( sprintf('InpostPayClient, error occurred when creating http client with bearer token. Exception message: %s', $throwable->getMessage()), $throwable->getCode(), $throwable ); } }

• Tworzymy implementację serwisu, który pobiera access token przy użyciu metody getBearerToken.

  <?php declare(strict_types=1); namespace Iteo\InpostPayClient\Client; use League\OAuth2\Client\Provider\Exception\IdentityProviderException; use League\OAuth2\Client\Provider\GenericProvider; use Iteo\InpostPayClient\SDK\Core\Exceptions\InpostPayEndpointException; /** * PHP Bearer Service implementation used for creating bearer token, needed to communication with Inpost Pay. */ final class InpostPayBearerService implements InpostPayBearerServiceInterface { private string $clientId; private string $clientSecret; private string $urlAccessToken; private ?string $urlAuthorize; private ?string $urlResourceOwnerDetails; //Zamienić w zależności od środowiska private const URL_ACCESS_TOKEN = 'https://sandbox-login.inpost.pl/auth/realms/external/protocol/openid-connect/token'; public function __construct(string $clientId, string $clientSecret, string $urlAccessToken = self::URL_ACCESS_TOKEN, string $urlAuthorize = null, string $urlResourceOwnerDetails = null) { $this->clientId = $clientId; $this->clientSecret = $clientSecret; $this->urlAccessToken = $urlAccessToken; $this->urlAuthorize = $urlAuthorize; $this->urlResourceOwnerDetails = $urlResourceOwnerDetails; } /** * {@inheritdoc} */ public function getBearerToken(): string { $provider = new GenericProvider([ 'clientId' => $this->clientId, 'clientSecret' => $this->clientSecret, 'urlAuthorize' => $this->urlAuthorize, 'urlAccessToken' => $this->urlAccessToken, 'urlResourceOwnerDetails' => $this->urlResourceOwnerDetails, ]); try { return $provider->getAccessToken('client_credentials')->getToken(); } catch (IdentityProviderException $exception) { throw InpostPayEndpointException::createClientException($exception); } } }

• W celu wykorzystania OAuth2.0 użyta została biblioteka: https://packagist.org/packages/league/oauth2-client?query=https%3A%2F%2Fpackagist.org%2Fpackages%2Fleague%2Foauth2-client%3Ftype%3Dcontao-module%26page%3D40&type=contao-module#2.7.0

Konfiguracja konta Merchanta - środowisko produkcyjne

1. Uzyskaj dostęp do środowiska produkcyjnego

• Dostęp do panelu Merchanta uzyskasz po podpisaniu Umowy o obsługę i rozliczanie transakcji.

• Jeśli jeszcze nie podpisałeś umowy, skontaktuj się ze swoim przedstawicielem handlowym InPost lub skorzystaj z formularza zamieszczonego w sekcji "Dla Biznesu" w zakładce "Oferta InPost Pay".

2. Zaloguj się do panelu Merchanta
   Adres panelu: https://merchant.inpost.pl

• Zaloguj się adresem e-mail wskazanym w umowie w polu ADMINISTRATOR.

• Jeśli to Twoje pierwsze logowanie – zarejestruj konto, używając podanego w umowie maila administratora, i postępuj zgodnie z instrukcją z wiadomości e-mail.
  Problem z logowaniem? Skontaktuj się z przedstawicielem handlowym lub napisz na bok.pay@inpost.pl

3. Uzupełnij dane sklepu

• Po zalogowaniu zobaczysz dane swojego sklepu.

• Kliknij w żółty przycisk EDYTUJ w prawym górnym rogu strony, aby uzupełnić szczegółowe dane wymagane do wygenerowania kluczy integracyjnych.

  Open

  

Wypełnij wszystkie pola formularza:

• Nazwa sklepu – będzie widoczna w aplikacji InPost Mobile.

• Kategoria – wybierz kategorię najlepiej odpowiadającą działalności sklepu.

• Technologia – wybierz platformę sklepu.
  Dla integracji API wybierz API Integration i podaj URL komunikacji z backendem sklepu.

4. Dodaj logo sklepu

   Twoje logo będzie widoczne w aplikacji InPost Mobile – zadbaj o jego jakość i format:

   1. Wklej link do logo, dostępny na publicznym serwerze (nie może to być np. google drive, czy cloud), najlepiej jeśli link prowadzi do logo na stronie Twojego sklepu (Jak umieścić logo na serwerze sklepu?)

   2. Logo nie może być większe niż 50 kb.

   3. Logo musi być zarówno w wersji jasnej, jak i ciemnej (w zależności z jakiej wersji aplikacji korzysta użytkownik)

   4. Aby logo było dobrze widoczne, powinno mieć wymiary dostosowane do minimalnej szerokości 108px i minimalnej wysokości 40px. Upewnij się, że Twój logotyp nie zawiera marginesów dla lepszej widoczności w aplikacji. Możesz załadować w formacie SVG i max wielkość pliku to 50 kb.

   5. Jeżeli logo, które chcesz wskazać ma format SVG upewnij się, że podczas renderowania pliku opcja "Preserve Illustrator Editing Capabilities" nie została zaznaczona.
      UWAGA! Po lewej stronie od linku dostępny jest podgląd logo. Upewnij się, że logo jest poprawne!

Zapisz dane klikając ZAPISZ w prawym górnym rogu.

Open

5. Wygeneruj klucze integracyjne (credentials)

Aby wygenerować client_id oraz client_secret należy uzupełnić szczegółowe dane każdego sklepu.

Open

Po uzupełnieniu wszystkich danych przejdź do zakładki Klucze InPost Pay i wygeneruj potrzebne dane, klikając w przycisk po prawej stronie ekranu UTWÓRZ KLUCZE INPOST PAY

Open

Następie zobaczysz Client ID oraz Client Secret, skopiuj je i wklej w panelu swojego sklepu.

Open

• Client ID – skopiuj i wklej do panelu sklepu

• Client Secret – zobaczysz jedynie klikając RESETUJ CLIENT SECRET

• Merchant Client ID – jest to klucz niezbędny do integracji z Widget 2.0. Całościowy opis tego elementu znajdziesz tu Widget 2.0

• POS ID – skopiuj i wklej do panelu sklepu

Open

Resetowanie Client Secret – w dowolnym momencie możesz zresetować Client Secret, używając ikony trzech kropek po prawej stronie tabeli.

Open

Open

WAŻNE: Każde wygenerowanie nowego Client Secret dezaktywuje poprzedni – pamiętaj o jego aktualizacji w swoim sklepie.

Open

6. Klucze API – Merchant Secret (opcjonalnie dla integracji ERP/API)

• Jeśli integrujesz zwroty i transakcje za pomocą API potrzebne credentiale znajdziesz wybierając w menu pozycję Klucze API

• Wygeneruj Klucz Merchant Secret używając żółtego przycisku w prawym górnym rogu ekrany UTWÓRZ SECRET

  Open

  

• Skopiuj Merchant Secret i wklej w panelu swojego sklepu

  Open

  

• W każdej chwili możesz zresetować Merchant Secret klikając Resetuj Secret

• Po resecie należy zaktualizować Merchant Secret w sklepie – do tego czasu API zwrotów nie będzie działać.

• Resetuj Merchant Secret tylko w razie potrzeby.

  Open

  

Open

Open

Jeśli zresetujesz Merchant Secret, skutkuje to koniecznością wpisania nowego w Twoim sklepie internetowym, do tego czasu komunikacja API będzie nieaktywna. Rekomendujemy reset tylko w niezbędnych przypadkach.

Pamiętaj o bezpieczeństwie!

Nie udostępniaj danych integracyjnych osobom trzecim.

Masz więcej sklepów? Jeśli masz więcej niż jeden sklep, po kliknięciu po lewej stronie w listę rozwijalną możesz przełączać się pomiędzy swoimi sklepami, zobaczysz listę sklepów, dla których została podpisana umowa na usługę.

Open

Jeśli masz pytania, skontaktuj się z nami: bok.pay@inpost.pl

Jak uzyskać link do swojego logo?

1. Skopiować go ze strony swojego sklepu

   1. Kliknij prawym przyciskiem myszy na logo swojego sklepu

   2. Wybierz „Otwórz obraz w nowej karcie”

   3. Skopiuj link z paska url

2. WooCommerce (oparte na WordPress)
   Dodawanie obrazu do biblioteki mediów:

   1. Zaloguj się do panelu administracyjnego WordPress.

   2. W menu po lewej stronie wybierz "Media" > "Dodaj nowe".

   3. Kliknij przycisk "Wybierz pliki" i wybierz obraz z komputera lub przeciągnij plik bezpośrednio do okna przeglądarki.

   4. Po zakończeniu przesyłania kliknij na dodany obraz, aby otworzyć jego szczegóły.

   5. W prawym panelu znajdziesz pole "Adres URL pliku" – to jest publiczny link do Twojego obrazu. Skopiuj go i używaj według potrzeb.

3. PrestaShop

   Dodawanie obrazu do biblioteki mediów:

    Aby dodać obraz i uzyskać do niego publiczny link, możesz skorzystać z poniższego sposobu:​

   1. Zaloguj się do panelu administracyjnego PrestaShop.

   2. Przejdź do "Katalog" > "Produkty".

   3. Wybierz produkt, do którego chcesz dodać obraz, lub utwórz nowy.

   4. W sekcji "Obrazy" kliknij "Dodaj plik" i wybierz obraz z komputera.

   5. Po przesłaniu obraz zostanie przypisany do produktu. Aby uzyskać publiczny link do tego obrazu:

      • Przejdź na stronę produktu w sklepie (frontend).​

      • Kliknij prawym przyciskiem myszy na obraz i wybierz "Kopiuj adres obrazu".​

      • Skopiowany adres to publiczny link do Twojego obrazu.​

   Uwaga: Możesz również skorzystać z klienta FTP (np. FileZilla). Przesłane pliki umieszczaj w katalogu /img/. Taki sposób wymaga podstawowej znajomości obsługi serwera FTP. W razie trudności skontaktuj się z administratorem lub znajdź poradnik w Google, np. wpisując frazę „jak przesłać plik przez FTP”.

4. Magento

   Dodawanie obrazu do biblioteki mediów:

   1. Zaloguj się do panelu administracyjnego Magento.

   2. Przejdź do "Content" > "Media" > "Wstawianie obrazów".

   3. Kliknij "Dodaj nowy obraz" i wybierz plik z komputera.

   4. Po przesłaniu obraz zostanie dodany do biblioteki mediów.

   5. Aby uzyskać publiczny link do obrazu:

      • Przejdź do "Content" > "Media" > "Biblioteka".​

      • Znajdź dodany obraz, kliknij na niego, a następnie skopiuj wyświetlony adres URL – to jest publiczny link do Twojego obrazu.​

   Uwaga: W Magento obrazy są często przechowywane w katalogu /pub/media/, więc publiczny link będzie miał strukturę: https://twojadomena.com/pub/media/nazwa_pliku.jpg.

Konfiguracja konta Merchanta - środowisko sandbox

Aby uzyskać dostęp do środowiska Sandbox uzupełnij i wyślij formularz kontaktowy korzystając z opcji Dla Biznesu i zakładki Sandbox.

Aplikacja testowa InPost Mobile

Na potrzeby testów udostępniamy Ci też nasze aplikacje testowe InPost Mobile:

• iOS instalujemy poprzez pobranie aplikacji z linku 

Join the InPost Mobile (Sandbox) beta   

• Android instalujemy poprzez pobranie z pliku
  

Jeśli po pobraniu pliku na urządzenie mobilne został on zapisany jako archiwum o nazwie "InPost Mobile [numer_wersji] Sandbox.apk.zip" zmień jego nazwę i usuń rozszerzenie ".zip". Po zapisaniu zmian powinieneś/aś otrzymać plik z rozszerzeniem .apk, który po otwarciu automatycznie zainstaluje/zaktualizuje aplikację. Jeżeli pomimo zmiany nazwy pliku nadal nie możesz zainstalować aplikacji, upewnij się, że w ustawieniach urządzenia zostały przyznane odpowiednie uprawnienia do instalacji aplikacji.

Chcesz testować na środowisku lokalnym?

W celu zapewnienia zdalnego dostępu do środowiska lokalnego, konieczne jest zastosowanie dodatkowego rozwiązania w postaci tunelowania ruchu z publicznej domeny na lokalny adres. Bez takiego obejścia nie ma możliwości bezpośredniego połączenia się z lokalnym środowiskiem.
Rekomendowane rozwiązanie
Aktualnie zalecanym narzędziem jest ngrok, który umożliwia szybkie skonfigurowanie tunelu między publicznym adresem URL a lokalnym środowiskiem. Wystarczy darmowe konto, które zapewnia jedną stałą domenę publiczną. Ta domena może przekierowywać ruch do lokalnej aplikacji lub zamkniętego środowiska testowego.
Wymagania
Po utworzeniu darmowej domeny publicznej należy przekazać jej adres w formularzu Kontakt -> Sandbox, aby otrzymać credentiale i cały ruch testowy mógł być kierowany na ten adres.

Wymagania techniczne po stronie Merchanta

Ruch wychodzący od InPost do Merchanta dla IP Proxy InPost 34.118.93.24, 34.116.145.216.

Mechanizm blokowania komunikacji z Merchantem w przypadku wystąpienia błędów

Podczas komunikacji synchronicznej z Merchantem może wystąpić szereg problemów związanych z komunikacją pomiędzy systemami, które mają wpływ na konwersje oraz korzystanie z aplikacji InPost Pay przez klienta, do których zaliczyć można:

• przetwarzanie żądań trwa zbyt długo z powodu spadku przepustowości systemu Merchanta

• usługa Merchanta może być przeciążona lub czekać na inne zasoby

• Merchant odpowiada niezgodnie z kontraktem (np. brak wymaganych danych) w wyniku czego występuje błąd walidacyjny

• Merchant zwraca błąd dotyczący problemów z serwerem (5xx)

Aplikacja InPost Pay w celu zachowania wysokiej konwersji koszyków i zamówień oraz obsługi klienta w aplikacji ma zaimplementowany mechanizm blokujący komunikacje z Merchantem, w przypadku wystąpienia wyżej wymienionych błędów.

Reguła blokowania komunikacji aplikacji InPost Pay z Merchantem:

Jeżeli w przeciągu 120 sekund wystąpi minimum 20 zapytań do Merchanta, w których minimum 90% będzie miało błędy:

• HttpServerErrorException np. response.status: 500

• ResourceAccessException np. Merchant timed out

• ResponseNotValidException np. Merchant odpowiada komunikatem 200, jednakże w przekazanym response.body dana lub dane są niepoprawne (np. brak wymaganych danych) przez co, aplikacja nie może poprawnie przetworzyć komunikatu,

to aplikacja InPost Pay zablokuje komunikacje z Merchantem.

W przypadku, gdy Merchant ma zablokowaną komunikacje, to przy próbie wywołania metody do InPost Pay otrzyma błąd 409 z komunikatem:

{ "error_code": "MERCHANT_DISABLE", "error_message": "Merchant with given id: <merchant_id> is DISABLED" }

W celu odblokowania komunikacji Merchant powinien skontaktować z InPost Pay poprzez zgłoszenie na adres integracjapay@inpost.pl.