FAQ InPost Pay

Owned by Michał Machowski
Last updated: Nov 13, 2024 by Joanna Wołosz
9 min read

 

  • Jaki jest limit ilości produktów “sugerowanych”?

Nie istnieje limit ilości produktów sugerowanych, jednak ze względu na przeznaczenie aplikacji InPost Pay dla urządzeń mobilnych, zaleca się dodawanie nie więcej niż 10 produktów sugerowanych.

  • Jak będzie zabezpieczana komunikacja pomiędzy Merchantem a InPost Pay? 

Zabezpieczeniu komunikacji pomiędzy Merchantem a InPost Pay została poświęcona sekcja dokumentacji pt. Merchant Backend API - Nagłówki.

  • Co się dzieje w przypadku, gdy klient decyduje się sfinalizować zakupy na stronie Merchanta? Czy koszyk jest usuwany z aplikacji InPost?

Możliwe są dwa przypadki:

  1. Klient utworzył nieopłacone zamówienie poprzez aplikację InPost, ale zakup został sfinalizowany po stronie Merchanta.
    W takim przypadku Merchant poprzez metodę POST /v1/izi/order/{order_id}/event przekazuje status ORDER_COMPLETED. Takie zamówienie jest widoczne w aplikacji InPost Mobile, jednak nie może zostać przez nią opłacone ani odrzucone.

  2. Klient powiązał koszyk z aplikacją InPost Mobile, a następnie sfinalizował zakupy na stronie sklepu Merchanta. W takim przypadku poprzez metodę DELETE /v1/izi/basket/{basket_id}/binding Merchant przekazuje do InPost informację o usunięciu koszyka z aplikacji wraz z flagą "if_basket_realized": true.

  • Co się dzieje w przypadku, gdy cena lub dostępność produktu w sklepie się zmieniła przed złożeniem zamówienia przez klienta? 

Każdorazowo przed złożeniem zamówienia, aplikacja InPost Pay pobiera pełne dane dotyczące koszyka ze strony Merchanta w tym cenę oraz dostępność produktu (z wykorzystaniem metody GET/v1/izi/basket/{basket_id}). Następnie pobrany koszyk jest porównywany z dotychczas przechowywanym w aplikacji koszykiem, a w momencie gdy ich wartości się różnią - prezentowany jest klientowi odpowiedni komunikat - koniec procesu utworzenia zamówienia na nieaktualnym koszyku. Kontynuacja wymaga odświeżenia koszyka.

  • Czy możliwe jest prowadzenie kilku koszyków jednocześnie u jednego Merchanta?

Nie, każdy koszyk tworzony na stronie Merchanta odpowiada jednemu koszykowi w aplikacji InPost. 

  • Produkty gratisowe – czy klient może “obejść” warunki promocji i dodać większą ilość gratisowych produktów korzystając z funkcji zwiększenia ilości w koszyku? 

Nie, ilość możliwych do dodania gratisowych produktów jest podyktowana warunkami promocji ustalonymi przez Merchanta, a ograniczenie następuje z wykorzystaniem metody iziCanBeBound.

  • Czy aplikacja będzie wysyłała do klienta przypomnienie o finalizacji koszyka? Czy można ustawić czas lub częstotliwość powiadomień według potrzeb Merchanta (aby uniknąć wysyłania powiadomień w czasie niekorzystnym pod względem biznesowym).

Obecnie rozwiązanie nie jest dostępne, będzie wprowadzane w kolejnych wersjach InPost Pay.

  • Kiedy koszyk jest usuwany z aplikacji InPost? Czy można ustawić czas “zawieszenia” koszyka?

Czas przechowywania koszyka w aplikacji InPost Pay jest wyznaczony przez Merchanta, przekazywany do Basket App w response na POST v1/izi/basket/{basket_id}/confirmation, obiekt “basket_expiration_date”.

  • Co w przypadku, gdy klient (zarejestrowany) raz kliknie dodanie produktu do koszyka używając widgetu InPost Pay, a później doda produkt używając przycisku sklepu?

Wówczas produkt zostanie dodany do koszyka sklepu, a w aplikacji mobilnej zostanie dodany do koszyka InPost Pay po jego odświeżeniu, w wyniku wywołania przez Merchanta metody PUT/v2/izi/basket/{basket_id}.

  • Co w przypadku sklepu, w którym zakupy w trybie gościa nie są możliwe?

Usługa InPost Pay dedykowana jest przede wszystkim klientom, którzy nie chcą zakładać konta klienta. InPost dokłada wszelkich starań, aby spełnić wszystkie wymagania klientów, dlatego skontaktuj się z opiekunem Projektu InPost Pay, aby wspólnie opracować satysfakcjonujące Cię rozwiązanie.

  • Czy klient może anulować opłacone zamówienie? Jak będzie ono prezentowane w InPost Pay?

Opłacone zamówienie nie może zostać anulowane z poziomu aplikacji InPost Pay. W takich sytuacjach obowiązuje standardowa procedura zwrotu.

  • Czy w InPost Pay prezentowana jest historia zamówień?

Tak, w aplikacji InPost Mobile znajdziesz nową sekcję ”Zakupy”, a w niej dwie zakładki: “Koszyki” oraz Zamówienia. “Zamówienia” przechowują wszystkie zamówienia, wraz z ich statusami, a po naciśnięciu w wybrane zamówienie wyświetlone zostaną jego szczegóły.

  • Jak wygląda komunikacja między komponentami? Czy np. Backend Merchanta musi ciągle nasłuchiwać aktualizacji koszyka ze strony InPost Pay? 

Komunikacja pomiędzy komponentami została szczegółowo opisana i przedstawiona na diagramach sekwencji w rozdziale dokumentacji technicznej pt. Diagramy sekwencji dla InPost Pay oraz Widget 2.0

  • Czy Merchant otrzymuje ze strony InPost Pay informację o tym, w jakiej formie klient opłacił zamówienie?

Informacja na temat formy płatności na zamówienie jest przekazywana w metodzie POST v1/izi/order, w obiekcie “payment_type”, który może przybierać wartości: CARD, CARD_TOKEN, GOOGLE_PAY, APPLE_PAY, BLIK_CODE, BLIK_TOKEN, PAY_BY_LINK, SHOPPING_LIMIT, DEFERRED_PAYMENT, CASH_ON_DELIVERY.

  • Co się dzieje w sytuacji, gdy wybrany przez klienta produkt/y nie mogą być dostarczone Paczkomatem?

Dostępne formy wysyłki oraz jej parametry takie jak szacowany czas dostarczenia oraz cena ustalane są odrębnie dla każdego produktu, w obiekcie “delivery_type” metody POST /v1/izi/basket/{basket_id}/confirmation.

  • Czy otrzymamy dostęp do aplikacji testowej?

Tak, udostępnimy wam aplikację na środowisku Sandbox, na której będzie można zasymulować działanie usługi InPost Pay.

  • Czy w InPost Pay prezentowane są klientom zgody marketingowe Merchanta? W jaki sposób?

Zgody prezentowane w InPost Mobile pobierane są ze strony Merchanta, w odpowiedzi na POST/v1/izi/basket/{basket_id}/confirmation zawierającej detale koszyka, w tym obowiązkowy obiekt “consents”. Możliwe jest przekazanie kilku zgód, wraz z linkami do pełnych treści (1 link dla 1 zgody), opisem, wersją oraz wymagalnością (opcjonalna, wymagana raz, wymagana zawsze). InPost Mobile przechowuje informacje o zgodach danego merchanta, tak aby zgody o wymagalności „gdy nowa wersja” były pobierane tylko raz dla danego nadanego ID i wersji zgody. Zgody wymagane „zawsze”, użytkownik musi zaakceptować przy każdym złożeniu zamówienia.

  • Czy w ramach InPost Pay możliwa jest forma dostawy “odbiór osobisty”? Czy jest możliwa wysyłka innym spedytorem?

W procesie InPost Pay obsługiwane są jedynie zamówienia z dostawą kurierem lub Paczkomatem InPost .

  •  Czy backend Merchanta może odpytać Basket App o status płatności?

Po wykonaniu płatności w aplikacji mobilnej, Basket App wywołuje metodę  POST/v1/izi/order/{order_id}/event do backendu Merchanta z informacją o wykonaniu płatności co jest z kolei wyzwalaczem dla Merchanta do dalszego przetwarzania zamówienia (pakowania i wysyłki). Merchant ma możliwość poinformowania tą samą metodą o kolejnych krokach w procesie realizacji zamówienia w tym m.in. przekazać numer referencyjny przesyłki.

  • Czy URL udostępniony przez/dla Merchanta służy do dwutorowej komunikacji? 

Tak, w komunikacji bierze udział backend Merchanta oraz moduł Basket App. Komunikacja przebiega dwutorowo, komponenty wymieniają informacje nt. powiązania koszyka, aktualizacji koszyka, zamówienia. Szczegółowy opis komunikacji został przedstawiony w rozdziale Diagramy sekwencji dla InPost Pay oraz Widget 2.0 dokumentacji technicznej.

  • Jaki zakres prac jest wymagany na frontendzie strony Merchanta? 

Merchant musi osadzić na swojej stronie dedykowany widget, który komunikuje się z backendem. Reszta komunikacja InPost Pay zachodzi pomiędzy backendem Merchanta a Basket App zgodnie z diagramami przedstawionymi w rozdziale Diagramy sekwencji dla InPost Pay oraz Widget 2.0.

  • Dlaczego w parametryzacji koszyka/zamówienia wymaganych jest podanie kilku cen, w tym “base price” i “final price”?

Kilka pól dotyczących cen umożliwia przedstawienie klientom zmian ceny koszyka/zamówienia tj. ceny przed i po obniżce. 

  • Załóżmy, że InPost nie może się dopukać na endpoind Merchanta, bo ten ma awarię serwera i nie odpowiada. W tym, czasie klient opłacił zamówienie korzystając z aplikacji mobilnej? Co się dzieje w przypadku braku komunikacji?

Mamy ustawione kolejki do sprawdzenia statusu i komunikacji z Merchantem, które w takiej sytuacji będą ponawiać próby komunikacji. Są one suplementarne do możliwości odświeżenia koszyka w aplikacji (force refresh, przeciągnięcie koszyka).

  • Mamy w swojej ofercie produkty, których nie chcemy objąć usługą InPost Pay (kwestie formalne). Czy można ją wyłączyć dla wybranych produktów?

Tak, do określenia możliwości dodania produktu do koszyka InPost Pay służy metoda widgetu iziCanBeBound.

  • Dlaczego nie mogę sparować koszyka za pomocą QR code? Brak reakcji ze strony aplikacji!

Przyczyną braku możliwości sparowania koszyka za pomocą QR code może być brak możliwości nawiązania połączenia ze strony Merchanta do Basket App. Powodem problemu może być niepoprawnie ustawiony adres usług lub występuje błąd przy autoryzacji. Skonsultuj z nami problem, wysyłając zgłoszenie na adres integracjapay@inpost.pl.

  • Zeskanowałem/am kod QR i pomyślnie sparowałem/am koszyk z numerem telefonu. Niestety gdy próbuje otworzyć koszyk w aplikacji otrzymuję komunikat “Ups…”.

Prawdopodobnie źródłem problemu jest parsowanie danych o koszyku. W odpowiedzi na POST /v1/izi/basket/{basket_id}/confirmation wysłane przez Basket App, Merchant przekazuje do InPost Pay pełne dane o koszyku. Należy sprawdzić, czy odpowiedź zawiera wszystkie wymagane pola wraz z poprawnymi wartościami, zgodnie z schema. Skonsultuj z nami problem, wysyłając zgłoszenie na adres integracjapay@inpost.pl.

  • Klikam w widget InPost Pay, ale produkt nie dodaje się do koszyka!

Sprawdź jaką wartość przyjmuje dla danego produktu  iziCanBeBound, FALSE blokuje możliwość dodania produktu do koszyka.

  • W jakiej formie Basket App przekazuje informacje dotyczące adresu? Czy dane są rozbijane na pola ulica, blok numer etc.?

Informacje o adresie dostawy przekazywane są w obiekcie delivery_address i parametrze address. Dodatkowy obiekt address_details zawiera dane rozbite na pola street, building, flat. Wartości w address_details są generowane automatycznie z danych podanych przez użytkownika, nie jest gwarantowana ich poprawność.

Pole browser zawiera część informacji z dalszych pól (tj. platform, architecture). W takim wypadku, należy te wartości "wyciągnąc" z browser_id i podstawić pod odpowiednie parametry np.

"browser": {

        "browser_id": "26e95acb-2bf4-4ca3-9bc9-e93ebf6fd6a6",

        "user_agent": "Testzilla 1.0",

        "description": "Test agent",

        "platform": "Ino Linux 2.0",

        "architecture": "x86-64",

        "data_time": "2023-02-08T10:41:19.664Z",

        "location": "Poland",

        "customer_ip": "127.0.0.1",

        "port": "8080"

    },

  • Skąd wziąć obiekt “browser_id” dla iziGetBindingData? 

“browser_id” jest zapisywane w cookies pod nazwą BrowserID.

  • Czym są parametry “location”, “data_time”, “port” obiektu browser?

"location" - lokalizacja użytkownika strony merchanta. jeśli Merchant nie jest w stanie zapewnić lokalizacji po IP użytkownika, może wprowadzić dowolną wartość np. "location": "Poland".

“data_time” - obecny czas, np. "data_time": "2023-02-08T10:41:19.664Z"

“port” - Jeżeli klient wchodzi przez https - 443, http - 80. np. "port": "8080"

  • Próbuje kilka razy sparować koszyk podając te same dane i nie otrzymuję notyfikacji push na telefonie.

Podczas prób parowania koszyka, InPost Pay weryfikuje reguły bezpieczeństwa/spam wiązania dla numeru telefonu. Jeśli dany numer telefonu był wykorzystywany wielokrotnie w krótkim okresie czasu, możliwość parowania zostanie tymczasowo zablokowana. Jest to oczekiwany rezultat, zapewniający bezpieczeństwo użytkownikom usługi InPost Pay.

  • Aplikacja “dziwnie się zachowuje”, większość akcji skutkuje pojawieniem się komunikatu “Ups…”.

Upewnij się, że używasz najnowszej wersji aplikacji InPost Mobile Sandbox. Jeżeli po reinstalacji problem nadal występuje skonsultuj go z nami, wysyłając zgłoszenie na adres integracjapay@inpost.pl.

  • Gdzie znajdę skrypt wtyczki?

Pełna dokumentacja jest udostępniona w rozdziale InPost Pay dokumentacji deweloperskiej InPost. Tam również znajdziesz sekcje dedykowane wtyczce, a skrypt można pobrać tutaj. Wciąż pracujemy nad udoskonaleniem dokumentacji, więc jeśli masz uwagi - zgłoś na adres integracjapay@inpost.pl.

  •  Czy urle dot. Merchant backend API będą wywoływane przez Widget czy aplikacja Inpost będzie z innego hosta się o nie odpytywać?

Z usług opisanych w  powyższym linku korzysta InPostPay (Basket App), widget ich nie wywołuje.

  • Czy klient będzie miał możliwość w aplikacji zmiany wariantu produktu (np. rozmiaru)? Przesyłamy uzupełnioną tablicę przy produkcie 'variants' ale taka opcja nie pojawia mi się w aplikacji.

API zostało przygotowane w docelowej wersji, ale aplikacja mobilna InPost na razie tego nie obsługuje. Zwiększenie komunikacji dwukierunkowej będzie się działo sukcesywnie.

  • Jakie kroki musimy zrealizować po naszej stronie, aby móc wprowadzić InPost Pay na środowisko produkcyjne? 

W celu ułatwienia procesu wprowadzania rozwiązania InPost Pay na środowisko produkcyjne, otrzymają Państwo dedykowaną checklistę z jasnym określeniem koniecznych do realizacji kroków jak również wskazaniem zespołów odpowiedzialnych za dany etap oraz zespołów wspierających.

  • Aplikacja niepoprawnie procesuje koszty dostawy. W koszyku widniał koszt XX.XX zł, ale w zamówieniu koszt jest równy 0 zł.

Zgodnie z dokumentacją obiekt “order_final_price” powinien zawierać całkowity koszt zamówienia wraz z uwzględnieniem kosztów wysyłki. Jeśli w obiekcie “order_final_price” nie zostanie przekazana odpowiednia wartość, tj. przekazana zostanie tylko wartość zamówionego produktu bez ceny dostawy, nie zostanie ona również uwzględniona w zamówieniu.

  • W aplikacji kwota prezentowana przy produkcie nie jest zwielokrotniona, pomimo że użytkownik dodał do koszyka kilka sztuk tego samego produktu. Czy to błąd aplikacji, czy może powinniśmy wysyłać zmultiplikowane “price” dla takiego przypadku?

Pracujemy nad aktualizacją aplikacji w tym zakresie, tak aby przeliczała kwotę zgodnie z ilością sztuk produktu w koszyku i prezentowała użytkownikowi odpowiednią sumę.

  • Czym jest pos_id w order_details?

pos_id jest unikalnym identyfikatorem Merchanta do obsługi usług związanych z płatnościami (portal merchanta, API). Jest nadawane przy onboardingu.

  • Czy InPost Pay odpowiada za nadawanie przesyłek? Czy to Merchant powinien samodzielnie obsłużyć nadanie przesyłki?

To Merchant jest odpowiedzialny za obsługę wysyłki. Powinien wygenerować etykietę oraz list przewozowy, a następnie przekazać listy przewozowe w polu “delivery_references_list”, planowany czas dostawy w polu “delivery_date” i informacje o cenie przesyłki oraz opcjach dodatkowych w “delivery_options”.

  • Na endpoint POST /v1/izi/order musimy odesłać dużą ilość danych. Wiele informacji dostajemy razem z requestem. Czy powinniśmy te dane walidować przed przekazaniem ich w odpowiedzi?

Dane powinny być walidowane przez Merchanta na pierwszym request, w którym przekazuje szczegóły koszyka, czyli na response w usłudze POST /v1/izi/basket/{basketId}/confirmation.

Flaga if_basket_realized umożliwia odróżnienie powodów odparowania koszyka, odróżnienie sytuacji gdy klient chce go sparować z wykorzystaniem innego numeru telefonu, od sytuacji w której koszyk został zrealizowany na stronie Merchanta i tym samym zakup nie został zrealizowany przez InPost Pay i nie będzie już prezentowany w aplikacji. Wszystkie powody usunięcia są przechowywane dla celów analitycznych.

  • Klikam “Kupuję i płacę” w aplikacji i otrzymuje “UPS…”

Problem leży po stronie hash koszyka, jego wartość wygenerowana przez stronę Merchanta nie równa się wartości przechowywanej w aplikacji przez co niemożliwe jest złożenie zamówienia. Powodem tej sytuacji może być np. zbyt dynamiczna wartość “delivery_date” przekazywana w odpowiedzi na GET /v1/izi/basket/{basket_id}.

  • Czy jako stronę z podziękowaniami, mogę umieścić dowolną stronę? Np. dotychczasową “Thank you page” sklepu?

Dbamy o to, aby usługa InPost Pay była możliwie najbardziej uniwersalna, dlatego zaprojektowaliśmy dedykowaną “Thank you page”, którą należy uwzględnić w metodzie iziGetOrderComplete. Stronę “Thank you page” wyświetla Merchant w momencie gdy zamówienie jest złożone ale nie opłacone i jest na niej informacja co użytkownik powinien dalej zrobić w InPost mobile, dlatego powinna to być dokładnie ta którą przygotowaliśmy.

  • Jakie waluty są obsługiwane w InPost Pay?

Obecnie obsługiwany jest tylko polski złoty (PLN).

  • Pytanie odnośnie "basket_notice": w POST /v1/izi/basket/{basket_id}/event. Czy dostępne w tym miejscu typy komunikatu ERROR i ATTENTION będą różniły się między sobą? Z perspektywy użytkownika aplikacji nie widzę różnicy między nimi.

Tak, z poziomu aplikacji ERROR i ATTENTION spowodują inne formy prezentacji komunikatu klientowi, np. po wprowadzeniu kodu rabatowego mogą wystąpić sytuacje wykluczające promocje lub tylko częściowe uwzględnienie kodu rabatowego. Zgodnie z nimi nastąpi przeliczenie koszyka, a informację o zastosowanym rabacie można zwrócić korzystając z ATTENTION. Jeśli wystąpi błąd w przeliczeniu koszyka, wtedy można przekazać informację o zdarzeniu korzystając z ERROR. 

Podsumowując ATTENTION służy do przekazania ważnych informacji do klienta o jego koszyku, a ERROR informuje o błędzie, uniemożliwiającym wykonanie określonego działania na koszyku.

Parametry “page_index” oraz “page_size” są parametrami stronicowania. Są to parametry opcjonalne, jeśli nie zostaną podane, zostanie ustawione default page 0 size 10.

  • W jaki sposób przekazać informację o możliwości płatności za pobraniem na danym koszyku?

W parametrze "payment_type" przekazujemy wartość CASH_ON_DELIVERY, a w parametrze "delivery_code_value" wartość COD. Płatność za pobraniem traktujemy jako jedną z dodatkowych opcji do wyboru w obrębie wybranej formy dostawy, dla której wprowadzamy dodatkowy koszt.
Przykład:

"payment_type": [
"CARD",
"CARD_TOKEN",
"GOOGLE_PAY",
"APPLE_PAY",
"BLIK_CODE",
"BLIK_TOKEN",
"PAY_BY_LINK",
"CASH_ON_DELIVERY"
]
"delivery": [
{
"delivery_type": "APM",
"delivery_date": "2023-09-04T23:59:59.000Z",
"delivery_price": {
"net": 8.13,
"gross": 10,
"vat": 1.87
}
},
{
"delivery_type": "COURIER",
"delivery_date": "2023-09-04T23:59:59.000Z",
"delivery_options": [
{
"delivery_name": "Kurier - pobranie",
"delivery_code_value": "COD",
"delivery_option_price": {
"net": 4.07,
"gross": 5,
"vat": 0.93
}
}
],
"delivery_price": {
"net": 8.13,
"gross": 10,
"vat": 1.87
}
}
]

  • Co w sytuacji, gdy produktu w koszyku nie da się dostarczyć ani Kurierem ani Paczkomatem?

Jeżeli dla danego koszyka nie można zrealizować dostawy Paczkomatem lub Kurierem, to w szczegółach koszyka Merchant przekazuje pustą tablicę z delivery:

"delivery":[].