Płatności Online AutopayPobierz

Płatności Online Autopay to kompleksowe rozwiązanie umożliwiające przyjmowanie płatności od klientów sklepów internetowych, obsługujące liczne metody płatności dostępne na rynku, takie jak przelewy, Pay by link, BLIK, Google Pay, Apple Pay. W niniejszej dokumentacji znajdziesz wszystko, czego potrzebujesz do szybkiego wdrożenia bramki płatności w sklepie internetowym. Dokumentacja Płatności Online Autopay zawiera części takie jak Obsługa transakcji i rozliczeń, Rejestracja i obsługa Punktów Rozliczeń pomiędzy AP a Platformą Marketplace Partnera, Rejestracja i obsługa Serwisów w oparciu o Formularz Integratorski, Dodatkowe rozszerzenia.

Definicje

Aplikacja – Aplikacja Mobilna Partnera, komunikująca się z SDK Systemu Płatności Online Autopay w celu rejestrowania Transakcji.

AP – Autopay Spółka Akcyjna z siedzibą w Sopocie przy ulicy Powstańców Warszawy 6, wpisana do rejestru przedsiębiorców prowadzonego przez Sąd Rejonowy Gdańsk-Północ w Gdańsku, VIII Wydział Gospodarczy Krajowego Rejestru Sądowego pod numerem KRS 0000320590, NIP 585-13-51-185, Regon 191781561, o kapitale zakładowym w wysokości 2 205 500 PLN (w całości opłaconym), nadzorowana przez Komisję Nadzoru Finansowego i wpisana do rejestru krajowych instytucji płatniczych pod numerem IP17/2013, właściciel Systemu.

BalancePoint (Punkt Rozliczeń) – obiekt w Systemie Płatności reprezentujący Sklep zintegrowany z Platformą Marketplace oraz zarejestrowany w Systemie Płatności przy użyciu formularza udostępnionego Partnerowi przez AP.

ClientHash - parametr w komunikatach; pozwala w sposób zanonimizowany przypisać Instrument płatniczy (np. Kartę) do Klienta. Na jego podstawie Partner może wywoływać kolejne obciążenia w modelu płatności automatycznych.

CommissionModel – model prowizyjny ustalony z Integratorem. Opisuje wartości prowizji za transakcje przekazywane AP oraz Integratorowi.

Dzień Roboczy – dzień tygodnia od poniedziałku do piątku, z wyłączeniem dni ustawowo wolnych od pracy.

Formularz Integratorski – strona internetowa, na której umieszczony jest formularz umożliwiający Klientowi rejestrację, edycje lub dodanie kolejnego Serwisu.

iFrame – metoda realizacji płatności Kartą za produkty/usługi oferowane przez Partnera, w której dane Karty wprowadzane są przez Klienta w dostarczonym przez AP dokumencie HTML, osadzonym bezpośrednio w Serwisie. Wywołanie formatki kartowej wymaga implementacji kodu JavaScript wykorzystującego dedykowaną bibliotekę AP.

Instrument Płatniczy (Kanał Płatności) – uzgodniony przez Klienta i jego dostawcę zbiór procedur lub zindywidualizowane urządzenie, wykorzystywane przez Klienta do złożenia zlecenia płatniczego np. Karta, PBL.

Narzędzie e-przelew – uzgodniony przez Partnera i AP zbiór procedur lub zindywidualizowane urządzenie, wykorzystywane przez Partnera do złożenia zlecenia płatniczego umożliwiającego realizację wypłatę środków z salda na rachunek bankowy Partnera lub Klienta oraz inny instrument płatniczy należący do Partnera lub Klienta. Udostępnienie funkcjonalności jest zależne od indywidualnych ustaleń między Partnerem i AP.

Integrator – Integratorami nazywamy partnerów, którzy wdrożyli w swoich systemach Płatności Online Autopay i umożliwiają ich aktywację z poziomu własnych rozwiązań. Do integratorów zaliczamy takie podmioty jak: Shoper, Shoplo, Sky-Shop, Gymsteer, Selly weryfikacje, FaniMani, AtomStore, Ebexo, Selly Azymut, PayNow, Comarch, SOTE.

IPN (Instant Product Notification) – natychmiastowe powiadomienie wysyłane z Systemu płatności online do Serwisu Partnera przekazujące zmianę statusu produktu. Struktura IPN jest podobna do ITN (rozszerzona jedynie o węzeł product).

ITN (Instant Transaction Notification) – natychmiastowe powiadomienie wysyłane z Systemu płatności online do Serwisu Partnera przekazujące zmianę statusu transakcji.

ISTN (Instant Settlement Transaction Notification) – Natychmiastowe powiadomienia o zmianie statusu transakcji rozliczeniowej. System niezwłocznie przekazuje powiadomienia o fakcie zlecenia transakcji rozliczeniowej (ew. wypłatach/zwrotach) oraz zmianie jej statusu.

ICN (Instant Configuration Notification) – Natychmiastowe powiadomienie o konfiguracji nowozarejestrowanego sklepu, przekazujące informacje o zmianie statusu kartowego w sklepie (np. w przypadku uruchamiania kart).

Karta - karta płatnicza wydana w ramach systemów VISA i Mastercard, dopuszczona regulacjami tychże systemów do realizacji Transakcji bez fizycznej jej obecności.

Klient (Płatnik) – osoba uiszczająca w Serwisie płatność za usługi lub produkty Partnera przy wykorzystaniu Systemu.

Koszyk produktów – jest to informacja o składowych płatności, przekazywana (w Linku płatności) do Systemu w celu późniejszego jej przetwarzania. Każdy produkt koszyka opisują dwa obowiązkowe pola: kwota składowa oraz pole pozwalające przekazać parametry charakterystyczne dla produktu.

Link płatności – żądanie umożliwiające start Transakcji wejściowej (opisanej w części Rozpoczęcie transakcji). Można go stosować bezpośrednio na stronach www (metoda POST), natomiast w mailach do Klientów należy posłużyć się Przedtransakcją w celu uzyskania krótkiego linka do płatności (metoda GET).

Link weryfikacyjny – adres URL kierujący do Przelewu weryfikacyjnego.

Marketplace – rozwiązanie płatnicze działające w ramach Systemu Płatności Online Autopay. Umożliwia Partnerowi obsługę platformy sprzedażowej, na której produkty lub usługi oferowane są Klientom przez Kontrahentów Partnera. Zaawansowane modele rozliczenia Transakcji oraz Transakcji Rozliczeniowych pozwalają na realizację płatności bezpośrednio od Klienta do Kontrahenta Partnera, z uwzględnieniem Koszyka produktów. Udostępnienie funkcjonalności jest zależne od indywidualnych ustaleń między Partnerem i AP.

Model Płatnika – model, w którym prowizję za przeprowadzoną transakcję opłaca klient na rzecz AP (koszt doliczany do kwoty transakcji). W tym przypadku klient podczas płatności akceptuje również regulamin AP.

Model Merchanta - model, w którym prowizja jest rozliczana między Autopay a partnerem i nie jest doliczana do kwoty transakcji opłacanej przez klienta.

Partner - podmiot będący odbiorcą środków z tytułu sprzedaży produktów lub usług dystrybuowanych przez Partnera w Serwisie.
Partner, w przypadku modelu Marketplace, to podmiot, niebędący konsumentem, zainteresowany obsługą przyjmowania przez AP należnych Partnerowi płatności za produkty lub usługi dystrybuowane przez Partnera.

Pay By Link (PBL) – narzędzie umożliwiające realizację płatności za pośrednictwem przelewu wewnątrzbankowego z rachunku Klienta na rachunek AP. Po zalogowaniu do bankowości internetowej - dane potrzebne do realizacji przelewu (dane informacyjne odbiorcy, numeru jego rachunku bankowego, kwota i data realizacji przelewu) są wypełnione automatycznie dzięki systemowi wymiany danych pomiędzy bankiem a AP.

Pełnomocnik techniczny – podmiot posiadający prawo dostępu do Rachunku Płatniczego Partnera, który autoryzuje ten dostęp (zgoda lub umowa). W systemie pełnomocnictwo jest reprezentowane przez konfigurację PlenipotentiaryID: jeden podmiot może mieć wiele pełnomocnictw dla różnych Partnerów.

Platforma Marketplace – platforma, na której udostępniona jest opcja rejestracji Punktów rozliczeń.

Płatność automatyczna – płatność dokonywana bez potrzeby każdorazowego wprowadzania danych Karty lub danych do autoryzacji przelewu.

Płatność jednym kliknięciem – jest to Płatność automatyczna zlecana przez Klienta.

Płatność cykliczna - jest to Płatność automatyczna zlecana bez udziału Klienta (przez Serwis Partnera).

Przedtransakcja - specyficzny (wykonywany w tle) sposób zamawiania linku do płatności.

Przelew weryfikacyjny – część procesu związana z rejestracją oraz edycją Serwisu/Serwisów Partnera w Systemie. Polega na wykonaniu przez Partnera przelewu środków, które zostaną automatycznie zwrócone przez AP, w celu weryfikacji danych i rachunku bankowego do wypłat środków do Partnera. Weryfikacja danych jest obowiązkiem AP wynikającym m.in. z Ustawy z dnia 16.11.2000 r. o przeciwdziałaniu praniu pieniędzy oraz finansowaniu terroryzmu. Każdy przelew weryfikacyjny musi otrzymać końcowy status weryfikacji (pozytywny lub negatywny) w ciągu 30 dni od opłacenia transakcji. Jeżeli status końcowy weryfikacji nie zostanie nadany w wyżej określonym czasie, system automatycznie nada jej status negatywny. Proces ten dotyczy weryfikacji, w której Autopay kieruje prośbę o uzupełnienie danych do klienta i nie otrzyma zwrotnej informacji niezbędnej do przeprowadzenia tejże weryfikacji.

Rachunek Płatniczy (Saldo) – rachunek płatniczy prowadzony przez AP dla Partnera, na którym gromadzone są środki wpłacone od Klientów. Udostępnienie funkcjonalności jest zależne od indywidualnych ustaleń między Partnerem i AP.

RPAN (Recurring Payment Activation Notification) – komunikat o aktywowaniu usługi płatności automatycznych.

RPDN (Recurring Payment Deactivation Notification) – komunikat o dezaktywacji usługi płatności automatycznych.

Serwis – strona lub strony internetowe Partnera zintegrowane z Systemem, na których Klient może nabyć od Partnera (lub od Kontrahenta Partnera w przypadku Marketplace) produkty lub usługi.
W przypadku Marketplace, obiekt w Systemie Płatności reprezentujący Marketplace Partnera. Dowiązywane są do niego wszystkie transakcje startowane przez wspomniany Marketplace.

Specyfikacja – dokumentacja opisująca komunikację pomiędzy Serwisem a Systemem.

System Płatności Online AP (System) – rozwiązanie informatyczno-funkcjonalne, w ramach którego AP udostępnia Partnerowi aplikację umożliwiającą procesowanie płatności Klientów dokonanych przy użyciu Instrumentów Płatniczych, a także weryfikację statusu płatności oraz odbiór płatności.

Szybki Przelew – realizacja płatności za pośrednictwem przelewu wewnątrzbankowego z rachunku Klienta na rachunek AP. Od płatności dokonywanych za pośrednictwem PBL płatność różni się koniecznością samodzielnego wypełnienia wszystkich danych potrzebnych do dokonania przelewu przez Klienta.

Transakcja - oznacza transakcję płatniczą w rozumieniu Ustawy z dnia 19 sierpnia 2011 r. o usługach płatniczych.

Transakcja wejściowa – część procesu obsługi płatności, dotycząca wpłaty dokonywanej przez Klienta do AP.

Transakcja rozliczeniowa – część procesu obsługi płatności, dotycząca przelewu wykonywanego przez AP na rachunek Partnera. Aby powstała Transakcja rozliczeniowa, Transakcja wejściowa musi zostać przez Klienta opłacona. Transakcja rozliczeniowa może dotyczyć pojedynczej transakcji wejściowej (wpłaty), bądź agregować ich wiele.

Ustawa – ustawa z dn. 19 sierpnia 2011 r. o usługach płatniczych.

Ważność linku – parametr określający moment, po przekroczeniu którego Link płatności przestaje być aktywny. Powinna być ustawiana przez parametr LinkValidityTime w Linku płatności.

Ważność transakcji – parametr określający moment, po przekroczeniu którego System płatności online blokuje i automatycznie zwraca wpłaty Klienta. Wartość domyślna obliczana jest poprzez dodanie 6 dni do dnia wybrania przez Klienta Kanału Płatności. Może ona być również ustawiana przez parametr ValidityTime w Linku płatności. W takim przypadku, po upłynięciu wskazanego czasu link przestaje być aktywny, a wpłaty są zwracane do Klienta. Maksymalna ważność transakcji to 31 dni.

WhiteLabel – model integracji, w którym Klient już w Serwisie dokonuje wyboru kanału płatności oraz akceptuje regulaminy (o ile konieczność ich akceptacji wynika z indywidualnych ustaleń między Partnerem i AP), a start transakcji zawiera wypełnione pole GatewayID (oraz w określonych przypadkach DefaultRegulationAcceptanceID lub RecurringAcceptanceID).

Adresy środowisk

TEST

• host_bramki: https://testpay.autopay.eu

• host_kartowy_bramki: https://testcards.autopay.eu

PRODUKCJA

• host_bramki: https://pay.autopay.eu

• host_kartowy_bramki: https://cards.autopay.eu

Obsługa transakcji i rozliczeń

Schemat działania usługi obsługi transakcji i rozliczeń

W Serwisie Partnera, po skompletowaniu zamówienia, Klientowi prezentowana jest opcja możliwości wykonania płatności z wykorzystaniem Systemu. Kliknięcie w odpowiedni link powoduje rozpoczęcie transakcji i otwarcie w nowym oknie:

a) dedykowanej strony Systemu przygotowanej przez AP, na której Klientowi prezentowana jest lista dostępnych Kanałów Płatności oraz podsumowanie zarejestrowanej transakcji lub

b) bezpośrednio strony Kanału Płatności (Banku, BLIK lub do płatności Kartą).

Po stronie Systemu następuje walidacja przekazanych parametrów i zapisanie transakcji z ustalonym okresem ważności. Jeśli w momencie walidacji, czas ważności linku będzie już przekroczony, Klientowi zostanie wyświetlony odpowiedni komunikat (weryfikacja ważności transakcji następuje także przy zmianie statusu płatności). Po pozytywnej weryfikacji parametrów transakcji (oraz po wybraniu Kanału Płatności), Klient dokonuje autoryzacji transakcji. W jej tytule, oprócz nadawanych przez System identyfikatorów, może być także umieszczany stały opis, ustalony wcześniej pomiędzy AP a Partnerem lub dynamiczna wartość przekazywana przez Partnera przy starcie transakcji.

Zalecany model integracji polega na nadaniu komunikatu rozpoczęcia transakcji w tle, tzn. bez przekierowania użytkownika do Systemu (patrz Przedtransakcja). W tym modelu, możliwe jest zastosowanie zaawansowanych form autoryzacji transakcji (WhiteLabel, płatności automatyczne, SDK mobilne), diagnozowania poprawności przekazywanych parametrów oraz wielu innych rozszerzeń.

Po zakończeniu autoryzacji transakcji (na stronie Kanału Płatności) klient powraca z niego do Systemu, gdzie następuje automatyczne przekierowanie Klienta do Serwisu Partnera.

WSKAZÓWKA: Szczegółowy opis struktury linku powrotu znajduje się w części Przekierowanie do serwisu Partnera.

Otrzymany z Kanału Płatności status autoryzacji (płatności) przekazywany jest z Systemu do Serwisu Partnera za pomocą komunikatu ITN. System będzie ponawiać wysyłanie komunikatów, aż do potwierdzenia odbioru przez Serwis Partnera lub upłynięcia czasu ważności powiadomienia. Transakcje, które zostaną zapłacone po opływie okresu ważności transakcji – zostaną zwrócone do Klienta (nadawcy przelewu).

Opcjonalnie System może powiadamiać o fakcie wystawienia Transakcji rozliczeniowej. Służy do tego odpowiednio zmodyfikowany komunikat ISTN.

Kroki integracji obsługi transakcji i rozliczeń

Dane wymagane podczas integracji obsługi transakcji i rozliczeń

Wymagane dane wymieniane podczas integracji różnią się dla środowiska testowego i produkcyjnego. Poniżej lista parametrów przekazywanych przez AP do Partnera oraz w kierunku odwrotnym.

Przekazywane są też informacje ogólne tj. aktywne kanały płatności wraz z grafikami (w wyniku odpytywania o listę dostępnych kanałów płatności).

Opcjonalnie, mogą pojawić się dodatkowe dane przekazywane przez Partnera do AP, na przykład: informacje o wymaganej zawartości koszyka i sposobie przetwarzania go (w raportach, rozliczeniach, panelu administracyjnym), dodatkowe wymagania (dla zasilenia salda przedpłaconego). Dla płatności automatycznych BLIK również domyślna długość życia aktywowanych płatności automatycznych oraz domyślna etykieta aktywowanych płatności automatycznych.

Dane wymieniane w środowisku testowym

Dane przekazywane przez Partnera do AP:

• Adres dla komunikatów ITN
• Adres dla komunikatów RPAN (może być ten sam, co dla komunikatów ITN) [dla płatności automatycznych]
• Adres dla komunikatów RPDN (może być ten sam, co dla komunikatów ITN) [dla płatności automatycznych]
• Adres powrotu z płatności (bez parametrów)

Dane przekazywane przez AP do Partnera:

• Adres Systemu płatności online
• ServiceID
• AcceptorID [dla portfeli w modelu WhiteLabel]
• Klucz współdzielony
• Mechanizm funkcji skrótu
• Adres testowego formularza
• Adres IP, z którego wysyłane są ITNy
• Adres do panelu administracyjnego
• Login
• Hasło

Dane przekazywane w środowisku produkcyjnym

Przez Partnera do AP:

• Adres dla komunikatów ITN
• Adres dla komunikatów RPAN (może być ten sam, co dla komunikatów ITN) [dla płatności automatycznych]
• Adres dla komunikatów RPDN (może być ten sam, co dla komunikatów ITN) [dla płatności automatycznych]
• Adres powrotu z płatności (bez parametrów)
• Adresy email dla raportów transakcyjnych
• Adresy email dla faktur i raportów rozliczeniowych
• Adresy email dla reklamacji (wysyłany w wiadomościach do płatników)

Przez AP do Partnera:

• Adres Systemu płatności online
• ServiceID
• AcceptorID [dla portfeli w modelu WhiteLabel]
• Klucz współdzielony
• Mechanizm funkcji skrótu
• Adres IP, z którego wysyłane są ITNy
• Adres do panelu administracyjnego
• Login
• Hasło

Implementacja interfejsów i procesów po stronie Partnera

W minimalnej wersji integracji należy zaimplementować obsługę rozpoczęcia transakcji, powrotu z niej oraz obsługę komunikacji ITN.

WSKAZÓWKA: Zaleca się zapoznanie ze schematem działania. W razie potrzeby warto zapoznać się także z dodatkowymi parametrami lub usługami.

Testy integracyjne i migracja na środowisko produkcyjne

Podczas wykonywania testów należy uzupełniać białe pola arkusza oraz podesłać go zwrotnie do AP, w celu potwierdzenia poprawności integracji przed migracją na środowisko produkcyjne.

WSKAZÓWKA: Przed wdrożeniem produkcyjnym zaleca się wykonać testy zgodnie ze scenariuszami testowymi w wersji podstawowej, a dla bardziej zaawansowanych integracji również zgodnie ze scenariuszami dodatkowymi.

Rozpoczęcie transakcji

Opis rozpoczęcia transakcji

Serwis Partnera inicjując transakcję przekazuje do Systemu płatności online parametry niezbędne do jej zrealizowania oraz późniejszego przekazania statusu płatności.

Wszystkie parametry przekazywane są metodą POST (Content-Type: application/x-www-form-urlencoded).

Protokół rozróżnia wielkość liter zarówno w nazwach jak i wartościach parametrów. Wartości przekazywanych parametrów powinny być kodowane w UTF-8 (oraz protokołem transportowym – zakodować przed wysłaniem, o ile narzędzie wykorzystane do wysyłki komunikatu nie robi tego samodzielnie, przykład kodowania: URLEncode).

Lista parametrów rozpoczęcia transakcji

WAŻNE! Kolejność atrybutów do wyliczenia Hash musi być zgodna z ich numeracją.

Sposób rozpoczęcia transakcji

Rozpoczęcie transakcji następuje przez przesłanie wywołaniem HTTPS kombinacji powyższych parametrów na ustalony w trakcie rejestracji usługi adres Systemu płatności online.

UWAGA: Liczba transakcji wystartowanych przez Partnera w ciągu jednej minuty może wynieść maksymalnie 100, chyba że Partner i AP ustalą wyższy limit w ramach zawartej umowy.

Przykład rozpoczęcia transakcji:

Adres:

• https://host_bramki/sciezka

Parametry:

• ServiceID=2

• OrderID=100

• Amount=1.50

    Hash=2ab52e6918c6ad3b69a8228a2ab815f11ad58533eeed963dd990df8d8c3709d1
  

Przesłanie komunikatu bez wszystkich wymaganych parametrów (ServiceID, OrderID, Amount i Hash) lub zawierającego błędne ich wartości, spowoduje zatrzymanie procesu płatności wraz z podaniem kodu błędu transakcji i krótką informacją o błędzie (brak powrotu na stronę Serwisu Partnera).

WAŻNE! "Para parametrów ServiceID i OrderID jednoznacznie identyfikuje transakcję. Niedopuszczalne jest powtórzenie się wartości parametru OrderID przez cały okres świadczenia usług przez System na rzecz jednego Serwisu Partnera (ServiceID)."

Opcjonalny parametr GatewayID służy do określenia Kanału Płatności, za pomocą którego ma zostać zrealizowana płatność. Pozwala to przenieść ekran wyboru Kanałów Płatności do Serwisu. Aktualna lista identyfikatorów Kanałów Płatności, wraz z logotypami, dostępna jest poprzez metodę gatewayList.

Komunikat rozpoczęcia transakcji może być nadany w tle, tzn. bez przekierowania użytkownika do Systemu płatności online. W tym modelu, samego wyboru Kanału Płatności, Klient także dokonuje w Serwisie Partnera.

Przekierowanie do Serwisu Partnera

Opis przekierowania do Serwisu Partnera

Niezwłocznie po zakończeniu autoryzacji transakcji przez Klienta jest on przekierowywany z witryny Kanału Płatności na witrynę Systemu płatności online, gdzie następuje automatyczne przekierowanie Klienta do Serwisu Partnera.

Przekierowanie realizowane jest poprzez wysłanie żądania HTTPS (metodą GET) pod ustalony wcześniej adres powrotu w Serwisie Partnera. Protokół rozróżnia wielkość liter zarówno w nazwach jak i wartościach parametrów.

Lista parametrów przekierowania do Serwisu Partnera

WAŻNE! Kolejność atrybutów do wyliczenia Hash musi być zgodna z ich numeracją.

Przykład komunikatu przekierowującego Klienta z Systemu płatności online do Serwisu Partnera

<https://sklep_nazwa/strona_powrotu?ServiceID=123458&OrderID=123402816&Hash=5432d69a66d721b2f5f785432bf5a1fc1b913bdb3bba465856a5c228fe95c1f8&

Powiadomienia natychmiastowe (ITN)

Opis powiadomień natychmiastowych

System przekazuje powiadomienia o zmianie statusu transakcji niezwłocznie po otrzymaniu takiej informacji z Kanału Płatności, a komunikat zawsze dotyczy pojedynczej transakcji. Potwierdzenia przesyłane są przez System płatności online na adres na serwerze Serwisu Partnera, ustalony w trakcie dodawania konfiguracji Serwisu Partnera.

UWAGA: Domena musi być publiczna i dostępna przez System. Domena musi być zabezpieczona ważnym certyfikatem, wystawionym przez publiczny urząd certyfikacji (Certificate authority) Serwer musi się przedstawiać pełnym łańcucha certyfikatów (Chain of Trust) Komunikacja musi się odbywać w oparciu o prokół TLS w wersji 1.2 lub 1.3 *Inne formy zazabezpieczenia połączenia np. VPN, mTLS muszą być uzgadniane indywidualnie z osobą odpowiedzialną za wdrożenie.

Przykład:

https://sklep_nazwa/odbior_statusu

Powiadomienie o zmianie statusu transakcji wejściowej polega na wysłaniu przez System dokumentu XML zawierającego nowe statusy transakcji.

Dokument wysyłany jest protokołem HTTPS (domyślnie port 443) – metodą POST, jako parametr HTTP o nazwie transactions. Parametr ten zapisany jest mechanizmem kodowania transportowego Base64.

Format dokumentu (XML)

	<?xml version="1.0" encoding="UTF-8"?>
	<transactionList>
		<serviceID>ServiceID</serviceID>
		<transactions>
			<transaction>
				<orderID>OrderID</orderID>
				<remoteID>RemoteID</remoteID>
				<amount>999999.99</amount>
				<currency>PLN</currency>
				<gatewayID>GatewayID</gatewayID>
				<paymentDate>YYYYMMDDhhmmss</paymentDate>
				<paymentStatus>PaymentStatus</paymentStatus>
				<paymentStatusDetails>PaymentStatusDetails</paymentStatusDetails>
			</transaction>
		</transactions>
		<hash>Hash</hash>
	</transactionList>

UWAGA: Węzeł transactions może zawierać jedynie jeden węzeł transaction (a więc powiadomienie dotyczy zawsze jednej transakcji). Wartości elementów orderID i amount dotyczących każdej z transakcji są identyczne z wartościami odpowiadających im pól, podanymi przez Serwis Partnera przy rozpoczęciu danej transakcji. Wyjątkiem są tutaj modele, w których prowizja doliczana jest do kwoty transakcji. Wówczas wartość amount w ITN jest powiększona o tą prowizję. Walidację kwot można wtedy przeprowadzić na podstawie opcjonalnego pola ITN startAmount. Należy jednak zgłosić zapotrzebowanie na to pole podczas integracji.

Lista zwracanych parametrów dla powiadomień natychmiastowych

WAŻNE! Kolejność atrybutów do wyliczenia Hash musi być zgodna z ich numeracją.

WSKAZÓWKA: Element hash (komunikatu) służy do autentykacji dokumentu. Opis sposobu obliczania skrótu znajduje się w części Bezpieczeństwo transakcji.

Odpowiedź na powiadomienie natychmiastowe

W odpowiedzi na powiadomienie oczekiwany jest status HTTP 200 (OK) oraz tekst w formacie XML (niekodowany Base64), zwracany przez Serwis Partnera w tej samej sesji HTTP, zawierający potwierdzenie otrzymania statusu transakcji.

Struktura potwierdzenia (XML)

	<?xml version="1.0" encoding="UTF-8"?>
	<confirmationList>
		<serviceID>ServiceID</serviceID>
		<transactionsConfirmations>
			<transactionConfirmed>
				<orderID>OrderID</orderID>
				<confirmation>Confirmation</confirmation>
			</transactionConfirmed>
		</transactionsConfirmations>
		<hash>Hash</hash>
	</confirmationList>

Opis pól potwierdzenia dla powiadomień natychmiastowych

WAŻNE! Kolejność atrybutów do wyliczenia Hash musi być zgodna z ich numeracją.

W wypadku braku poprawnej odpowiedzi na wysłane powiadomienia, System podejmie kolejne próby przekazania najnowszego statusu transakcji po upływie określonego czasu. Serwis Partnera powinien wykonywać własną logikę biznesową (np. mail z potwierdzeniem), jedynie po pierwszym komunikacie o danym statusie płatności.

WSKAZÓWKA: Warto zapoznać się ze Schematem ponawiania komunikatów ITN/ISTN/IPN/RPAN/RPDN.

Szczegółowy opis zachowania i zmiany statusów płatności (paymentStatus)

Wybór przez Klienta metody płatności każdorazowo spowoduje wysłanie statusu PENDING. W kolejnym komunikacie ITN system dostarczy status SUCCESS lub FAILURE.

UWAGA Status PENDING nie zostanie wysłany, jeśli:

• klient zrezygnuje lub powróci z ekranu listy metod płatności bez wybrania konkretnej metody. W tym wypadku od razu zostanie wysłany status FAILURE. Nie pojawi się status PENDING, ponieważ klient nie rozpoczął procesu płatności.
• status finalny (SUCCESS lub FAILURE) zostanie dostarczony przed wysłaniem ITN ze statusem PENDING.

Dla pojedynczej transakcji (o unikatowych parametrach OrderID oraz RemoteID) nie może nastąpić zmiana statusu SUCCESS na PENDING lub SUCCESS na FAILURE.

W każdym przypadku może nastąpić zmiana statusu szczegółowego – paymentStatusDetails (kolejne komunikaty o zmianie statusu szczegółowego są jedynie informacyjne i nie powinny prowadzić do ponownego wykonania opłacanej usługi/wysyłki produktu itp.).

W szczególnych przypadkach użycia może nastąpić zmiana statusu:

a) FAILURE na SUCCESS (np. po zatwierdzeniu przez konsultanta AP transakcji wpłaconej z błędną kwotą. Takie zachowania wymaga specjalnych uzgodnień biznesowych i nie jest włączone domyślnie),

b) SUCCESS na FAILURE (np. po wywołaniu wielu transakcji z tym samym OrderID, ale różnym RemoteID). Taki przypadek występuje w sytuacji rozpoczęcia przez Klienta wielu płatności z tym samym OrderID (np. Klient zmienia decyzję, jakim Kanałem płatności chce opłacić transakcję). Każda z rozpoczętych przez niego płatności generuje ITNy i poszczególne transakcje Partner powinien rozróżnić na podstawie parametru RemoteID. Ponieważ czas otrzymania statusu FAILURE może być bardzo różny, może się zdarzyć otrzymanie takiego statusu po odebraniu SUCCESS (oczywiście z innym RemoteID). W takim wypadku, komunikat ITN powinien być potwierdzany, ale nie powinien pociągać za sobą anulowania statusu transakcji w systemie Partnera.

Obsługa statusów transakcji z ITN – model uproszczony

W modelu, w którym nie jest potrzebne powiadamianie mailem/smsem Klienta o statusach innych niż SUCCESS, można ograniczyć ilość informacji zapisywanych do bazy Serwisu oraz śledzenie zmian RemoteID.

Wystarczy:

• dla statusów innych niż SUCCESS, za każdym razem potwierdzać ITN poprawną strukturą odpowiedzi, statusem CONFIRMED oraz poprawnie policzoną wartością pola Hash,

• w przypadku otrzymania pierwszego statusu SUCCESS, dodać również aktualizację statusu, jego czasu i RemoteID w bazie Serwisu oraz realizację procesów biznesowych (powiadomienia do Klienta o zmianie statusu, wykonania opłacanej usługi/wysyłki produktu itp.),

• w przypadku otrzymania kolejnego statusu SUCCESS, za każdym razem potwierdzać ITN poprawną strukturą odpowiedzi, statusem CONFIRMED oraz poprawnie policzoną wartością pola Hash, bez aktualizacji bazy Serwisu oraz bez procesów biznesowych.

Obsługa statusów transakcji z ITN – model pełny

W modelu, w którym potrzebna jest cała historia zmian statusów transakcji i/lub powiadamianie Klienta o ważniejszych zmianach statusów transakcji należy zastosować logikę przybliżoną do poniższego opisu.

Bezpieczeństwo transakcji

Opis bezpieczeństwa transakcji

W Systemie płatności online zastosowano kilka mechanizmów zwiększających bezpieczeństwo realizowanych przy jego użyciu transakcji. Transmisja między wszystkimi stronami transakcji realizowana jest z użyciem bezpiecznego połączenia opartego na protokole TLS z 2048-bitowym kluczem.

Dodatkowo, komunikacja zabezpieczana jest funkcją skrótu obliczoną z wartości pól komunikatu i współdzielonego klucza (sam klucz współdzielony przechowywany jest w Systemie w postaci zaszyfrowanej algorytmem AES-ECB).

Jako funkcja skrótu wykorzystywany jest algorytm SHA256 lub SHA512 (metoda ustalana na etapie konfigurowania danego Serwisu Partnera w Systemie płatności online). Domyślna funkcja to SHA256.

Obliczanie wartości funkcji skrótu

Opis sposobu obliczania wartości funkcji skrótu oraz przykłady obliczeń dla podstawowych komunikatów.

UWAGA: Przykłady nie uwzględniają wszystkich możliwych pól opcjonalnych, dlatego w razie występowania takich pól w konkretnym komunikacie, należy uwzględnić je w funkcji skrótu w kolejności zgodnej z numerem obok pola.

Sposób obliczania wartości funkcji skrótu – pole Hash

Wartość funkcji skrótu, służąca do autentykacji komunikatu, obliczana jest od łańcucha zawierającego sklejone pola komunikatu (konkatenacja pól). Sklejane są wartości pól, bez nazw parametrów, a pomiędzy kolejnymi (niepustymi) wartościami wstawiany jest separator (w postaci znaku |). Kolejność sklejania pól jest zgodna z kolejnością ich występowania na liście parametrów w dokumentacji.

WAŻNE! W przypadku braku opcjonalnego parametru w komunikacie lub w przypadku pustej wartości parametru, nie należy używać separatora!

Do powstałego w powyższy sposób łańcucha doklejany jest na jego końcu klucz, współdzielony między Serwis Partnera i System płatności online. Z tak powstałego łańcucha obliczana jest wartość funkcji skrótu i stanowi ona wartość pola Hash komunikatu.

Hash = funkcja(wartości_pola_1_komunikatu + "|" + wartości_pola_2_komunikatu + "|" + ... + "|" + wartości_pola_n_komunikatu + "|" + klucz_współdzielony);

Przykładowe obliczenia wartości funkcji skrótu podczas rozpoczęcia transakcji

Dane Serwisu Partnera:
ServiceID = 2

klucz_współdzielony = 2test2

Adres bramki https://host_bramki/sciezka

a. Rozpoczęcie transakcji.

Wywołanie POST bez koszyka, z parametrami:

ServiceID=2
OrderID=100
Amount=1.50

Hash=2ab52e6918c6ad3b69a8228a2ab815f11ad58533eeed963dd990df8d8c3709d1

gdzie

Hash=SHA256(“2|100|1.50|2test2”)

b. Rozpoczęcie transakcji. Wywołanie POST z koszykiem.

WSKAZÓWKA: Opcja szczegółowo omówiona w części Koszyk produktów.

ServiceID = 2

OrderID = 100

Amount = 1.50

Product (opisany niżej)

klucz_współdzielony = 2test2

Koszyk produktów (XML)

	<?xml version="1.0" encoding="UTF-8"?>
	<productList>
	   <product>
		  <subAmount>1.00</subAmount>
		  <params>
			 <param name="productName" value="Nazwa produktu 1" />
		  </params>
	   </product>
	   <product>
		  <subAmount>0.50</subAmount>
		  <params>
			 <param name="productType" value="ABCD" />
			 <param name="ID" value="EFGH" />
		  </params>
	   </product>
	</productList>

Po zakodowaniu funkcją base64 otrzymujemy wartość parametru Product:

PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz48cHJvZHVjdExpc3Q+PHByb2R1Y3Q+PHN1YkFtb3VudD4xLjAwPC9zdWJBbW91bnQ+PHBhcmFtcz48cGFyYW0gbmFtZT0icHJvZHVjdE5hbWUiIHZhbHVlPSJOYXp3YSBwcm9kdWt0dSAxIiAvPjwvcGFyYW1zPjwvcHJvZHVjdD48cHJvZHVjdD48c3ViQW1vdW50PjAuNTA8L3N1YkFtb3VudD48cGFyYW1zPjxwYXJhbSBuYW1lPSJwcm9kdWN0VHlwZSIgdmFsdWU9IkFCQ0QiIC8+PHBhcmFtIG5hbWU9IklEIiB2YWx1ZT0iRUZHSCIgLz48L3BhcmFtcz48L3Byb2R1Y3Q+PC9wcm9kdWN0TGlzdD4=

Wartość Hash liczona jest w następujący sposób:

Hash=SHA256(“2|100|1.50|PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz48cHJvZHVjdExpc3Q+PHByb2R1Y3Q+PHN1YkFtb3VudD4xLjAwPC9zdWJBbW91bnQ+PHBhcmFtcz48cGFyYW0gbmFtZT0icHJvZHVjdE5hbWUiIHZhbHVlPSJOYXp3YSBwcm9kdWt0dSAxIiAvPjwvcGFyYW1zPjwvcHJvZHVjdD48cHJvZHVjdD48c3ViQW1vdW50PjAuNTA8L3N1YkFtb3VudD48cGFyYW1zPjxwYXJhbSBuYW1lPSJwcm9kdWN0VHlwZSIgdmFsdWU9IkFCQ0QiIC8+PHBhcmFtIG5hbWU9IklEIiB2YWx1ZT0iRUZHSCIgLz48L3BhcmFtcz48L3Byb2R1Y3Q+PC9wcm9kdWN0TGlzdD4=|2test2”)

Przykładowe obliczenia wartości funkcji skrótu podczas powrotu Klienta do Serwisu Partnera

Dane Serwisu Partnera:

ServiceID = 2

klucz_współdzielony = 2test2

<https://sklep_nazwa/strona_powrotu?ServiceID=2>&OrderID=100&Hash=254eac9980db56f425acf8a9df715cbd6f56de3c410b05f05016630f7d30a4ed

gdzie

Hash=SHA256("2|100|2test2")

Przykładowe obliczenia wartości funkcji skrótu w komunikacie ITN

Dane Serwisu Partnera:

serviceID = 1

klucz_współdzielony = 1test1

ITN (XML)

	<?xml version="1.0" encoding="UTF-8"?>
	<transactionList>
	   <serviceID>1</serviceID>
	   <transactions>
		  <transaction>
			 <orderID>11</orderID>
			 <remoteID>91</remoteID>
			 <amount>11.11</amount>
			 <currency>PLN</currency>
			 <gatewayID>1</gatewayID>
			 <paymentDate>20010101111111</paymentDate>
			 <paymentStatus>SUCCESS</paymentStatus>
			 <paymentStatusDetails>AUTHORIZED</paymentStatusDetails>
		  </transaction>
	   </transactions>
	   <hash>a103bfe581a938e9ad78238cfc674ffafdd6ec70cb6825e7ed5c41787671efe4</hash>
	</transactionList>

gdzie

Hash=SHA256(“1|11|91|11.11|PLN|1|20010101111111|SUCCESS|AUTHORIZED|1test1”)

Przykładowa odpowiedź (XML)

	<?xml version="1.0" encoding="UTF-8"?>
	<confirmationList>
	   <serviceID>1</serviceID>
	   <transactionsConfirmations>
		  <transactionConfirmed>
			 <orderID>11</orderID>
			 <confirmation>CONFIRMED</confirmation>
		  </transactionConfirmed>
	   </transactionsConfirmations>
	   <hash>c1e9888b7d9fb988a4aae0dfbff6d8092fc9581e22e02f335367dd01058f9618</hash>
	</confirmationList>

gdzie wartość

Hash=SHA256("1|11|CONFIRMED|1test1");

Przykładowe obliczenia wartości funkcji skrótu w odpytaniu o listę Kanałów Płatności

Dane Serwisu Partnera:

serviceID = 1

messageID = cfb91538ad854d74813ea76893cc020c

klucz_współdzielony = 1test1

gdzie wartość

Hash=SHA256("1|cfb91538ad854d74813ea76893cc020c|1test1");

Odpowiedź na powyższe wywołanie może być następująca:

	<?xml version="1.0" encoding="UTF-8"?>
	<list>
	   <serviceID>1</serviceID>
	   <messageID>cfb91538ad854d74813ea76893cc020c</messageID>
	   <gateway>
		  <gatewayID>19</gatewayID>
		  <gatewayName>Przelew PKOBP</gatewayName>
		  <gatewayType>Szybki Przelew</gatewayType>
		  <bankName>INTELIGO</bankName>
		  <iconURL>https://host/sciezka/19.png</iconURL>
		  <statusDate>2015-10-14 12:12:31</statusDate>
	   </gateway>
	   <gateway>
		  <gatewayID>106</gatewayID>
		  <gatewayName>platnosc testowa PG</gatewayName>
		  <gatewayType>PBL</gatewayType>
		  <bankName>NONE</bankName>
		  <statusDate>2015-10-14 12:12:31</statusDate>
	   </gateway>
	   <hash>8b69fcfac99ab7113b6b6c60e42fd6ec316a161027bcf2eb63bf6a5ff595fcd3</hash>
	</list>

gdzie wartość

Hash=SHA256(“1|cfb91538ad854d74813ea76893cc020c|19|Przelew PKOBP|Szybki Przelew|INTELIGO|https://host/sciezka/19.png|2015-10-14 12:12:31|106|platnosc testowa PG|PBL|NONE|2015-10-14 12:12:31|1test1”);

Rejestracja i obsługa Serwisów w oparciu o Formularz Integratorski

Schemat działania usługi dodawania i edycji Serwisów

Niniejszy dokument opisuje zasady związane z wymianą komunikatów pomiędzy AP, a Platformą Integratora w ramach funkcjonalności dodawania i edycji Serwisów, która odbywa się za pomocą technologii REST oraz Web-Services protokołu SOAP (Usługa udostępnia swoją definicję w postaci dokumentu WSDL).

Partner udostępnia na swojej Platformie odnośnik, którego wybór przez Klienta powoduje wysłanie komunikatu do AP celem otrzymania linku kierującego do Formularza Integratorskiego przygotowanego przez AP (efekty wizualne takie jak kolorystyka, czy logo Integratora na formularzu ustalane są podczas integracji).

Dane zebrane na formularzu (po jego wypełnieniu przez Klienta) są przetwarzane przez AP, gdzie w zależności od typu formularza wykonywana jest rejestracja/edycja/dodanie kolejnego serwisu.  Po pozytywnym przejściu tego kroku dane konfiguracyjne serwisu oraz linki weryfikacyjne (przy edycji danych niewrażliwych linki się nie pojawią) wysyłane są asynchronicznie do Integratora kanałami ustalonymi w trakcie integracji. Równolegle odbywa się również wysyłka do Klienta wiadomości email zawierającej linki do płatności weryfikacyjnej.

Klient w tym czasie zostaje automatycznie przekierowany na stronę powrotu Integratora (adres zostaje ustalony w trakcie integracji) lub zostaje mu zaprezentowana strona z podziękowaniem za skorzystanie z usługi, na której opcjonalnie mogą znaleźć się linki do płatności weryfikacyjnych i/lub link do Platformy Integratora.

Po opłaceniu przez Klienta transakcji weryfikacyjnej, AP sprawdza poprawność danych zadeklarowanych przez tegoż Klienta podczas rejestracji serwisu. W przypadku nadania przez AP pozytywnego statusu weryfikacji, usługa płatności w serwisie zostaje aktywowana, a do Klienta zostaje wysłana wiadomość z regulaminem zaakceptowanym przez niego na formularzu rejestracyjnym.

WAŻNE! Produkcyjna wersja usługi znajduje się za firewallem. Dostęp jest przydzielany dla skończonej i zdefiniowanej w trakcie integracji puli IP. Nie dotyczy to środowiska testowego.

WAŻNE! Dla jednego Integratora na danym środowisku (test/produkcja) przewidziany jest jeden identyfikator Platformy (PlatformID) oraz klucz współdzielony wykorzystywany do budowania hasha dla wszystkich komunikatów wymienianych pomiędzy Integratorem a AP w obrębie procesu rejestracji i edycji serwisów.

WAŻNE! Wygenerowany przez AP link prowadzący do formularza rejestracji/edycji danych serwisu ma domyślny czas ważności 24 godzin. Wartość ta może być zmieniona na prośbę Integratora.

WAŻNE! Niedopuszczalne jest udostępnianie w jakiejkolwiek formie (również w kodzie uruchamianej na serwerze osób trzecich) danych autoryzacyjnych do usługi udostępnianej przez AP (PlatformID/klucz współdzielony).

WAŻNE! Jeśli podczas rejestracji lub edycji sklepu klient wybierze kilka walut, przy pomocy których mogą być wykonywane płatności w sklepie, każda z tych walut wraz z przypisanym do niej rachunkiem rozliczeniowym musi zostać osobno zweryfikowana, poprzez przelew weryfikacyjny.

WAŻNE! Na formularzu służącym do edycji danych, przed wyświetlaniem na nim aktualnych danych Serwisu musi nastąpić weryfikacja tożsamości. W tym celu Klientowi zaprezentowane są dwa kanały weryfikacji: wiadomość sms lub email. Po wyborze jednego z nich, do Klienta jest wysyłany kod weryfikacyjny (do tego celu wykorzystany jest numer telefonu lub adres email podany przez Klienta w procesie rejestracji), który musi zostać przez niego wpisany na dodatkowym formularzu. Po poprawnym uzupełnieniu tego pola i jego weryfikacji przez AP Klient otrzymuje dostęp do formularza edycji danych wraz z całą jego zawartością.

UWAGA: W części Obsługa transakcji i rozliczeń opisane zostały funkcjonalności i sposób ich integracji w zakresie związanym z obsługą płatności dla Serwisu oraz usługami powiązanymi z obsługą płatności np. schematem rozliczeń.

W modelu Integratora nie są dostępne poniższe funkcje części transakcyjnej:

a) Dane wymieniane podczas integracji

b) Koszyk produktów

Dane wymieniane podczas integracji Formularza Integratorskiego

Aktywne Kanały Płatności wraz z grafikami przesyłane przez AP do Partnera.

Dane wymieniane w środowisku testowym

Dane przekazywane przez AP do Partnera:

• Adres Systemu płatności online
• Adres usługi (adresy, na których wystawione są poszczególne metody, z których może skorzystać Integrator)
• PlatformID
• ServiceID (dla usługi Przelewu weryfikacyjnego)
• Klucz współdzielony dla usługi rejestracji i edycji
• Klucz współdzielony dla usługi Przelewu weryfikacyjnego
• Mechanizm funkcji skrótu
• Adres IP, z którego wysyłane są ITNy
• Adres do panelu administracyjnego dla integratora (opcja)
• Login
• Hasło

Dane przekazywane przez Partnera do AP:

• Adres ITN po przelewie weryfikacyjnym
• Adres powrotu po przelewie weryfikacyjnym
• Informacja o walutach jakie mają być dostępne dla sklepów integratora
• Informacja o kanałach wysyłki konfiguracji Serwisu oraz Linków Weryfikacyjnych
• Adres email Integratora w przypadku wysyłki konfiguracji serwisów poprzez adres email
• Adres, pod którym Integrator wystawi usługę do odbierania komunikatów ICN
• Informacja w przypadku zmiany domyślnego czasu ważności linka prowadzącego do formularza rejestracji/edycji danych serwisu (domyślnie 24 godziny)

Dane przekazywane w środowisku produkcyjnym

Przez AP do Partnera:

• Adres Systemu płatności online
• Adres usługi (adresy, na których wystawione są poszczególne metody, z których może skorzystać Integrator)
• PlatformID
• Metoda : registerCompany
• ServiceID (dla usługi Przelewu weryfikacyjnego)
• Klucz współdzielony dla usługi rejestracji i edycji
• Klucz współdzielony dla usługi Przelewu weryfikacyjnego
• Mechanizm funkcji skrótu
• Adres IP, z którego wysyłane są ITNy
• Adres do panelu administracyjnego dla integratora (opcja)
• Login
• Hasło

Przez Partnera do AP:

• Adres IP, z którego następuje połączenie do WS
• Adres ITN po przelewie weryfikacyjnym
• Adres powrotu po przelewie weryfikacyjnym
• Adresy email dla raportów rozliczeniowych dla Integratora
• Informacja o walutach jakie mają być dostępne dla sklepów integratora
• Informacja o kanałach wysyłki konfiguracji Serwisu oraz Linków Weryfikacyjnych
• Adres email Integratora w przypadku wysyłki konfiguracji serwisów poprzez adres email
• Adres, pod którym Integrator wystawi usługę do odbierania komunikatów ICN
• Adres, pod którym integrator wystawi usługę do odbierania powiadomień o statusie kartowym (konieczne w przypadku, kiedy Integrator chce taką informację otrzymywać)
• Informacja w przypadku zmiany domyślnego czasu ważności linka prowadzącego do formularza rejestracji/edycji danych serwisu (domyślnie 24 godziny)

Pobranie przez Integratora linku do Formularza Integratorskiego

Wymiana komunikatów (w formacie JSON) pomiędzy AP, a Platformą Integratora, realizujących funkcjonalność pobierania linków do formularza rejestracji/edycji serwisów odbywa się za pomocą technologii REST. Dostęp do usługi zabezpieczony jest poprzez filtrowanie adresów IP.

Opis pól wysyłanych w komunikacie żądania do AP

WAŻNE! Kolejność atrybutów do wyliczenia Hash musi być zgodna z ich numeracją.

Przykład 1:

	{
	   "platformId":1,
	   "messageId":"22111111112411111111111111111130",
	   "messageTime":"2016-07-20T09:35:00.000",
	   "hash":"43688c048e451fba81ea7895cca13c5b6eb953a6ddf23c6089918259163381e1",
	   "formAction":"REGISTRATION",
	   "formParams":{
		  "SERVICE_URL":"https://serivce-integrator-test.pl",
		  "COMMISSION_MODEL":{
			 "PLN":"5"
		  },
		  "IS_CARDS_ENABLED":"TRUE"
	   }
	}

Przykład 2:

	{
	   "platformId":1,
	   "messageId":"11111111111111111111111111211254",
	   "messageTime":"2016-07-20T09:35:00.000",
	   "hash":"b16c13f8b2f6e43d583689287aaa8ca87181d037df8083c9d678e34a23983750",
	   "formAction":"UPDATE",
	   "acceptorId":120,
	   "serviceIds":[
		  11111
	   ]
	}

Przykład 3:

	{
	   "platformId":1,
	   "messageId":"11111111111111111111111111211254",
	   "messageTime":"2016-07-20T09:35:00.000",
	   "hash":"b16c13f8b2f6e43d583689287aaa8ca87181d037df8083c9d678e34a23983750",
	   "formAction":"UPDATE",
	   "formParams":{
		  "SERVICE_URL":"https://serivce-integrator-test-nowy.pl",
		  "COMMISSION_MODEL":{
			 "PLN":"4"
		  },
	   "acceptorId":120,
	   "serviceIds":[
		  11111
	   ]
	}

Przykład 4:

	{
	   "platformId":1,
	   "requestId":"22111111112411111111111111111131",
	   "messageTime":"2016-07-20T09:35:00.000",
	   "hash":"81bc2f50d4284cf4c638c4cf0ca6a07827eccf937152db151979b394a67a863d",
	   "formAction":"ADD_SERVICE",
	   "acceptorId":222222,
	   "formParams":{
		  "SERVICE_URL":"https:// serivce-integrator-test.pl ",
		  "COMMISSION_MODEL":{
			 "PLN":"5"
		  },
		  "IS_CARDS_ENABLED":"TRUE"
	   }
	}

Opis pól komunikatu odpowiedzi do Integratora

WAŻNE! Kolejność atrybutów do wyliczenia Hash musi być zgodna z ich numeracją.

WSKAZÓWKA: Poprawna odpowiedź – status http 200.

WSKAZÓWKA: Odpowiedź z komunikatem błędu – status http 400.

Przykład poprawnej odpowiedzi:

	{
		"link": "https://integrator-form-domain/ e2287514541105a2eda2b85751e88be5998aec8c99cd83ba3073365ce1a243a1",
		"hash": "f9e02e83fe50920ee2efb0d2322b6200a71f3afcc366893487ced7ad2330a610",
		"messageId": "11111111111111111111111111111229",
		"formHash": "e2287514541105a2eda2b85751e88be5998aec8c99cd83ba3073365ce1a243a1"
	}

Przykłady błędnej odpowiedzi:

	{
		"errors": [
			{
				"field": "acceptorId",
				"error": "Value for field acceptorId required!",
				"errorCode": 6003
			}
		]
	}

>

	{
		"errors": [
			{
				"field": "messageTime",
				"error": "Message time is outdated",
				"errorCode": 6016
			}
		]
	}

>

	{
		"errors": [
			{
				"field": "hash",
				"error": "Invalid hash",
				"errorCode": 6000
			}
		]
	}

Kody błędów

Powrót Klienta do Platformy Integratora

Przekierowanie Klienta może nastąpić bezpośrednio po poprawnym wykonaniu rejestracji/edycji serwisu lub może być udostępnione na stronie z podziękowaniem w formie odnośnika.

Wysyłka danych konfiguracyjnych Serwisu oraz Linków Weryfikacyjnych (ICN)

Po wysłaniu formularza przez Klienta i finalizacji procesu rejestracji/edycji, AP musi wysłać dane konfiguracyjne Serwisu oraz Linków Weryfikacyjnych do Integratora. Może się to odbyć na kilka sposobów. Kanały wysyłki ustalane są z Integratorem w trakcie integracji.

Umożliwiamy dostarczenie powyższych informacji poprzez wymianę komunikatów w technologii REST, Web-Services lub poprzez wysyłkę wiadomości email pocztą elektroniczną.

Każdy z kanałów wysyłek ma swój system ponawiania w przypadku nieudanej próby przesłania informacji do Integratora.

Ze względów bezpieczeństwa sugerujemy, aby wymiana informacji o danych konfiguracyjnych była wykonywana przy użyciu jednej z technologii REST lub Web-Services na zestawionym tunelu IPSec lub poprzez filtrowanie adresów IP.

Do powiązania komunikatu ICN (otrzymanego przez Integratora) z konkretną rejestracją Klienta z formularza służy pole formHash, które jest wysyłane zarówno w komunikacie ICN jak i w odpowiedzi na odpytanie o link do formularza. Dzięki temu Integrator posiada informację, dla której rejestracji otrzymał dane konfiguracyjne w komunikacie ICN.

Wysyłka danych konfiguracyjnych poprzez REST

Wymiana komunikatów pomiędzy AP, a Serwisem Partnera realizujących funkcjonalności dodawania i edycji Serwisów Partnerów odbywa się za pomocą technologii REST. Komunikaty wysyłane są w formacie JSON.

Opis pól wysyłanych w komunikacie żądania do Integratora

WAŻNE! Kolejność atrybutów do wyliczenia Hash musi być zgodna z ich numeracją.

Przykład 1.

	{
	   "acceptorID":11111,
	   "serviceID":22222,
	   "serviceKey":"sa22a2729462f643cf4c989dddcf226b99b3a6bda11db43a433ab31a7ec2abe925",
	   "hash":"580a285b9bf95e60d4eaeb470d32858a5f0191a2a51b40a18ee7612fa9ced187",
	   "verificationLinks ":[
		  {
			 "link":"sampleLink",
			 "currency":"PLN"
		  }
	   ],
	   "panelLogin":"sample panel login",
	   "panelPassword":"sample panel password",
	   "panelAddress":"sample panel address",
	   "formHash":"sample form hash",
	   "method":"REGISTER"
	}

Opis pól komunikatu odpowiedzi do AP

	{
		"resultStatus":"OK",
		"description":"sample description"
	}

Wysyłka danych konfiguracyjnych poprzez Web-Services

Wymiana komunikatów pomiędzy AP, a Serwisem Partnera realizujących funkcjonalności dodawania i edycji Serwisów Partnerów odbywa się za pomocą technologii Web-Services protokołu SOAP.

Usługa ta udostępnia swoją definicję w postaci dokumentu WSDL (Web Service Definitions Language), dostarczanego przez AP podczas integracji.

Opis pól wysyłanych w komunikacie żądania do Integratora – InstantConfigurationNotificationRequest

	<xsd:element name="InstantConfigurationNotificationRequest">
		<xsd:complexType>
			<xsd:sequence>
				<xsd:elementname="InstantConfigurationNotification" type="tns: InstantConfigurationNotification "/>
			</xsd:sequence>
		</xsd:complexType>
	</xsd:element>

	<xsd:complexType name=" InstantConfigurationNotification ">
		<xsd:sequence>
			<xsd:sequence>
				<xsd:element name="AcceptorID" type="xsd:int"/>
				<xsd:element name="ServiceID" type="xsd:int"/>
				<xsd:element name="ServiceKey" type="xsd:string"/>
				<xsd:element name="Hash" type="xsd:string"/>
				<xsd:element minOccurs="0" name="VerificationLinks" type="tns:VerificationLinks"/>
				<xsd:element minOccurs="0" name="PanelLogin" type="xsd:string"/>
				<xsd:element minOccurs="0" name="PanelPassword" type="xsd:string"/>
				<xsd:element minOccurs="0" name="PanelAddress" type="xsd:string"/>
				<xsd:element name="FormHash" type="xsd:string"/>
				<xsd:element name="Method" type="tns:Method"/>
			</xsd:sequence>
		</xsd:sequence>
	</xsd:complexType>

	<xsd:complexType name="VerificationLink">
		<xsd:sequence>
			<xsd:element name="Currency" type="xsd:string"/>
			<xsd:element name="Link" type="xsd:string"/>
		</xsd:sequence>
	</xsd:complexType>

	<xsd:complexType name="VerificationLinks">
		<xsd:sequence>
			<xsd:element maxOccurs="unbounded" name="VerificationLink" type="tns:VerificationLink"/>
		</xsd:sequence>
	</xsd:complexType>

	<xsd:simpleType name="Method">
		<xsd:restriction base="xsd:string">
			<xsd:enumeration value="REGISTER"/>
			<xsd:enumeration value="UPDATE"/>
			<xsd:enumeration value="ADD_SERVICE"/>
		</xsd:restriction>
	</xsd:simpleType>

Opis pól komunikatu

WAŻNE! Kolejność atrybutów do wyliczenia Hash musi być zgodna z ich numeracją.

Przykład 1.

	<SOAP-ENV:Envelope
		xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
		<SOAP-ENV:Header/>
		<SOAP-ENV:Body>
			<ns2: InstantConfigurationNotificationRequest
				xmlns:ns2="http://integrator/ws/">
				< InstantConfigurationNotification>
					<AcceptorID>11111</AcceptorID>
					<ServiceID>22222</ServiceID>                
					<ServiceKey>22a2729462f643cf4c989dddcf226b99b3a6bda11db43a433ab31a7ec2abe925</ServiceKey>                
					<Hash>580a285b9bf95e60d4eaeb470d32858a5f0191a2a51b40a18ee7612fa9ced187</Hash>
					<VerificationLinks>
						<VerificationLink>
							<Currency>PLN</Currency>
							<Link>sampleLink</Link>
						</VerificationLink>
					  </VerificationLinks>
					<FormHash>generated_hash</FormHash>
		   <Method>REGISTER</Method>
				</ InstantConfigurationNotification>
			</ns2: InstantConfigurationNotificationRquest>
		</SOAP-ENV:Body>
	</SOAP-ENV:Envelope>

Komunikat odpowiedzi do AP

	<xsd:element name=" InstantConfigurationNotificationResponse">
		<xsd:complexType>
			<xsd:sequence>
				<xsd:element name="Result" type="tns:ResultStatus"/>
				<xsd:element name="Description" type="xsd:string"/>
			 </xsd:sequence>
		</xsd:complexType>
	</xsd:element>

>

	<xsd:simpleType name="ResultStatus">
		<xsd:restriction base="xsd:string">
			<xsd:enumeration value="OK"/>
			<xsd:enumeration value="ERROR"/>
		</xsd:restriction>
	</xsd:simpleType>

Opis pól komunikatu

	<SOAP-ENV:Envelope
		xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
		<SOAP-ENV:Header/>
		<SOAP-ENV:Body>
			<ns2: InstantConfigurationNotificationResponse
				xmlns:ns2="http://integrator/ws/">
				 <Result>OK</Result>
				 <Description>sample description</Description>
			</ns2: InstantConfigurationNotificationResponse>
		</SOAP-ENV:Body>
	</SOAP-ENV:Envelope>

Wysyłka danych konfiguracyjnych poprzez Email

Informacje o serwisie są wysyłane na adres email wskazany przez integratora w formie pliku zabezpieczonego hasłem. Numer telefonu, na który mają być wysyłane hasła jest ustalany z Integratorem w trakcie integracji.

Natychmiastowe powiadomienie o zmianie statusu płatności kartowych

Proces udostępnienia sklepowi płatności za pośrednictwem kart płatniczych, wymaga weryfikacji sklepu zarówno po stronie AP jak i po stronie administratora płatności kartowych, dlatego uruchomienie zazwyczaj trwa dłużej niż sama aktywacja sklepu.

System umożliwia wysyłkę natychmiastowego powiadomienia w przypadku włączania lub wyłączenia możliwości wykonywania płatności przy użyciu kart płatniczych w sklepie, aby zapewnić spójność konfiguracji sklepu pomiędzy Platformą Integratora a AP. Zostało to zrealizowane poprzez wysyłkę komunikatu w formacie JSON przy użyciu technologii REST.

UWAGA: Poprawne działanie usługi wymaga zaimplementowania po stronie Integratora metody pozwalającej na przyjęcie wspomnianego komunikatu.

Opis pól komunikatu wysyłanego do Integratora

WAŻNE! Kolejność atrybutów do wyliczenia Hash musi być zgodna z ich numeracją.

Przykład.

	{
	"serviceId":"1111111",
	"orderId":"22222",
	"cardsStatus":"ACTIVE",
	"hash":"81eb70b8f2c4576bfb375a7ccbfcfb196b235556bcc329aa40a3dc8bfd"
	}

Opis pól komunikatu zwrotnego do AP

WAŻNE! Kolejność atrybutów do wyliczenia Hash musi być zgodna z ich numeracją.

Przykład.

	{
	"serviceId":"1111111",
	"orderId":"22222",
	"confirmation":"CONFIRMED",
	"hash":"81eb70bcb8f2c4576bfb375a7ccbfcfb196b2355986556b29aa40a3dc8bfd"
	}

Pobranie przez integratora danych Serwisu – GetAMLCompanyData

GetAMLCompanyDataReq

Komunikat służący do uzyskania aktualnych w Systemie danych Partnera. Ponieważ AP jest zobligowane, aby gwarantować aktualność danych obsługiwanych Partnerów, może nastąpić ich aktualizacja (w dowolnym momencie) na podstawie zaufanych źródeł zewnętrznych. W związku z powyższym, wymagane jest, aby przed każdym wyświetleniem na Platformie Integratora, nastąpiła ich aktualizacja na Platformie poprzez wywołanie metody GetAMLCompanyData.

	<xsd:element name="GetAMLCompanyDataReq">
		<xsd:complexType>
			<xsd:sequence>
				<xsd:element name="AcceptorID" type="xsd:int"/>
				<xsd:element name="Header" type="tns:Header"/>
			</xsd:sequence>
		</xsd:complexType>
	</xsd:element>

Opis pól komunikatu

	<xsd:complexType name="Header">
		   <xsd:sequence>
				   <xsd:element name="PlatformId" type="xsd:string"/>
				   <xsd:element name="MessageTime" type="xsd:dateTime"/>
				   <xsd:element name="RequestId" type="xsd:long"/>
				   <xsd:element name="Hash" type="xsd:string"/>
			 </xsd:sequence>
	</xsd:complexType>

Opis pól komunikatu

WAŻNE! Kolejność atrybutów do wyliczenia Hash musi być zgodna z ich numeracją.

"GetAMLCompanyDataResp"

Komunikat jest odpowiedzią na GetAMLCompanyDataResp.

	<xsd:element name="GetAMLCompanyDataResp">
		<xsd:complexType>
			<xsd:sequence>
				<xsd:element name="Result" type="xsd:string"/>
				<xsd:element name="ErrorStatus" type="xsd:string" nillable="true"/>
				<xsd:element name="Company" type="tns:Company"/>
				<xsd:element name="isServiceActive" type="xsd:boolean" nillable="true"/>
			</xsd:sequence>
		</xsd:complexType>
	</xsd:element>

Opis pól komunikatu

WSKAZÓWKA: Typ komunikatu Company, oraz poszczególne jego składowe, opisano szczegółowo w części Typy złożone.

Zmiana konfiguracji Serwisu – "UpdateConfiguration"

"UpdateConfigurationReq"

Komunikat umożliwiający zmianę konfiguracji Sklepu przez Integratora bez konieczności wykonywania przelewu weryfikacyjnego.

	<xsd:element name="UpdateConfigurationReq">
		<xsd:complexType>
			<xsd:sequence>
				<xsd:element name="ServiceID" type="xsd:int" minOccurs="0"/>
				<xsd:element name="Header" type="tns:Header"/>
				<xsd:element name="ConfigurationData" type="tns:ConfigurationData"/>
				<xsd:element name="Currency" type="xsd:string"/>
			</xsd:sequence>
		</xsd:complexType>
	</xsd:element>

Opis pól komunikatu

	<xsd:complexType name="Header">
		<xsd:sequence>
			<xsd:element name="PlatformId" type="xsd:string"/>
			<xsd:element name="MessageTime" type="xsd:dateTime"/>
			<xsd:element name="RequestId" type="xsd:long"/>
			<xsd:element name="Hash" type="xsd:string"/>
		</xsd:sequence>
	</xsd:complexType>

Opis pól komunikatu

WAŻNE! Kolejność atrybutów do wyliczenia Hash musi być zgodna z ich numeracją.

	<xsd:complexType name="ConfigurationData">
		<xsd:sequence>
			<xsd:element name="isTransactionRefundAllowed" type="tns:BooleanType" minOccurs="0"/>
			<xsd:element name="CommissionModel" type="xsd:long" nillable="true"/>
			<xsd:element name="isCardsPaymentRequired" type="tns:BooleanType" minOccurs="0"/>
			<xsd:element name="ServiceUrl" type="xsd:string" minOccurs="0"/>
		</xsd:sequence>
	 </xsd:complexType>

Opis pól komunikatu

UWAGA: Podany w ServiceUrl adres musi zawierać stałą część domeny.
Na przykład zmiana adresu: https://nazwasklepu.integrator.pl na https://nazwasklepu.pl

"UpdateConfigurationResp"

Komunikat jest odpowiedzią na UpdateConfigurationReq.

	<xsd:element name="UpdateConfigurationResp">
		<xsd:complexType>
			<xsd:sequence>
				<xsd:element name="Result" type="xsd:string"/>
				<xsd:element name="ErrorStatus" type="xsd:string" nillable="true"/>
			</xsd:sequence>
		</xsd:complexType>
	</xsd:element>

Opis pól komunikatu

Anulowanie aktualnej edycji serwisu, która jest w trakcie weryfikacji – "CancelUpdate"

Komunikat służący do anulowania edycji danych serwisu, który jest aktualnie w trakcie weryfikacji. Poprawne wykonanie CancelUpdate umożliwia wysłanie danych z formularza celem edycji danych sklepu, bez oczekiwania na finalny status weryfikacji poprzedniej edycji.

UWAGA: Próby pobrania linka do formularza dla serwisu, który jest aktualnie w trakcie weryfikacji zakończą się błędem: SHOP_IN_VERIFICATION_STATUS.

CancelUpdateReq

	<xsd:element name="CancelUpdateReq">
		<xsd:complexType>
			<xsd:sequence>
				<xsd:element name="ServiceID" type="xsd:int" minOccurs="0"/>
				<xsd:element name="AcceptorID" type="xsd:int" minOccurs="0"/>
				<xsd:element name="Header" type="tns:Header"/>
			</xsd:sequence>
		</xsd:complexType>
	</xsd:element>

Opis pól

CancelUpdateResp

	<xsd:element name="CancelUpdateResp">
		<xsd:complexType>
			<xsd:sequence>
				<xsd:element name="Result" type="xsd:string"/>
				<xsd:element name="ErrorStatus" type="xsd:string" nillable="true"/>
			</xsd:sequence>
		</xsd:complexType>
	</xsd:element>

Opis pól

Typy złożone

Header

Typ komunikatu służący do przekazywania danych nagłówka dotyczących bezpieczeństwa komunikacji i poprawności przesyłanych danych.

	<xsd:complexType name="Header">
		<xsd:sequence>
			<xsd:element name="PlatformId" type="xsd:string"/>
			<xsd:element name="MessageTime" type="xsd:date"/>
			<xsd:element name="RequestId" type="xsd:long"/>
			<xsd:element name="Hash" type="xsd:string"/>
		</xsd:sequence>
	</xsd:complexType>

Opis pól komunikatu

WAŻNE! Kolejność atrybutów do wyliczenia Hash musi być zgodna z ich numeracją.

Address

Ten typ komunikatu służy do przekazywania adresu danego podmiotu.

	<xsd:complexType name="Address">
		<xsd:sequence>
			<xsd:element name=”Address” type=”xsd:string/>
			<xsd:element name=”PostalCode” type=”xsd:string/>
			<xsd:element name=”City” type=”xsd:string/>
			<xsd:element name=”Country” type=”xsd:string/>
		</xsd:sequence>
	</xsd:complexType>

Opis pól komunikatu

NIPType

Typ opisujący numer NIP z ograniczeniem od 2 do 15 znaków.

	<xsd:simpleType name="NIPType">
		<xsd:restriction base="xsd:string">
			<xsd:minLength value="2"/>
			<xsd:maxLength value="15"/>
		</xsd:restriction>
	</xsd:simpleType>

Currency

Typ opisujący walutę.

	<xsd:simpleType name="Currency">
		<xsd:restriction base="xsd:string">
			<xsd:enumeration value="PLN"/>
			<xsd:enumeration value="EUR"/>
			<xsd:enumeration value="USD"/>
			<xsd:enumeration value="GBP"/>
			<xsd:enumeration value="CZK"/>
		</xsd:restriction>
	</xsd:simpleType>

ForeignTransferModeType

System przelewu rozliczeniowego w przypadku rachunku zagranicznego.

	<xsd:simpleType name="ForeignTransferModeType">
		<xsd:restriction base="xsd:string">
			<xsd:enumeration value="SWIFT"/>
			<xsd:enumeration value="SEPA"/>
		</xsd:restriction>
	</xsd:simpleType>

Beneficials

Obiekt jest listą typów beneficjentów rzeczywistych Partnera.

	<xsd:complexType name="Beneficials">
		<xsd:sequence>
			<xsd:element name="Beneficial" type="tns:Beneficial" minOccurs="0" maxOccurs="2"/>
		</xsd:sequence>
	</xsd:complexType>

Beneficial

Obiekt zawiera typ beneficjenta rzeczywistego oraz ewentualną listę beneficjentów tego typu.

	<xsd:complexType name="Beneficial">
		<xsd:sequence>
			<xsd:element name="BeneficialType" type="xsd:int"/>
			<xsd:element name="BeneficialOwners" type="tns:BeneficialOwners" minOccurs="0" />
		</xsd:sequence>
	</xsd:complexType>

Opis pól komunikatu

BeneficialOwners

Typ opisuje listę beneficjentów rzeczywistych.

	<xsd:complexType name="BeneficialOwners">
		<xsd:sequence>
			<xsd:element name="BeneficialOwner" type="tns:BeneficialOwner" minOccurs="0" maxOccurs="8"/>
		</xsd:sequence>
	</xsd:complexType>

BeneficialOwner

Typ opisuje dane pojedynczego beneficjenta rzeczywistego.

	<xsd:complexType name="BeneficialOwner">
		<xsd:sequence>
			<xsd:element name="FirstName" type="xsd:string" nillable="false"/>
			<xsd:element name="LastName" type="xsd:string" nillable="false"/>
			<xsd:element name="Citizenship" type="xsd:string"/>
			<xsd:element name="Share" type="xsd:int" minOccurs="0"/>
		</xsd:sequence>
	</xsd:complexType>

Opis pól komunikatu

Plenipotentiary

Typ komunikatu opisujący pełnomocnika.

	<xsd:complexType name="Plenipotentiary">
		<xsd:sequence>
			<xsd:element name="FirstName" type="xsd:string"/>
			<xsd:element name="LastName" type="xsd:string"/>
			<xsd:element name="Citizenship" type="xsd:string"/>
			<xsd:element name="Pesel" type="xsd:string" minOccurs="0"/>
			<xsd:element name="BirthDate" type="xsd:string" minOccurs="0"/>
			<xsd:element name="BirthCountry" type="xsd:string" minOccurs="0"/>
			<xsd:element name="DocumentType" type="xsd:string" minOccurs="0"/>
			<xsd:element name="Document" type="xsd:string" minOccurs="0"/>
			<xsd:element name="DocumentExpirationDate" type="xsd:string" minOccurs="0"/>
			<xsd:element name="DocumentCountryId" type="xsd:string" minOccurs="0"/>
		</xsd:sequence>
	</xsd:complexType>

Opis pól komunikatu

Partners

Typ opisuje listę wspólników.

	<xsd:complexType name="Partners">
		<xsd:sequence>
			<xsd:element name="Partner" type="tns:Partner" minOccurs="0" maxOccurs="7"/>
		</xsd:sequence>
	</xsd:complexType>

Partner

Typ komunikatu opisujący wspólnika.

	<xsd:complexType name="Partners">
		<xsd:sequence>
			<xsd:element name="FirstName" type="xsd:string"/>
			<xsd:element name="LastName" type="xsd:string"/>
			<xsd:element name="Citizenship" type="xsd:string"/>
			<xsd:element name="Pesel" type="xsd:string" minOccurs="0"/>
			<xsd:element name="BirthDate" type="xsd:string" minOccurs="0"/>
			<xsd:element name="BirthCountry" type="xsd:string" minOccurs="0"/>
			<xsd:element name="DocumentType" type="xsd:string" minOccurs="0"/>
			<xsd:element name="Document" type="xsd:string" minOccurs="0"/>
			<xsd:element name="DocumentExpirationDate" type="xsd:string" minOccurs="0"/>
			<xsd:element name="DocumentCountryId" type="xsd:string" minOccurs="0"/>
		</xsd:sequence>
	</xsd:complexType>

Opis pól komunikatu

Service

Typ komunikatu opisujący Serwis Partnera.

	<xsd:complexType name="Service">
		<xsd:sequence>
			<xsd:element name="Name" type="xsd:string" nillable="false"/>
			<xsd:element name="ServiceUrl" type="xsd:string" nillable="false"/>
			<xsd:element name="UrlITN" type="xsd:string" nillable="false"/>
			<xsd:element name="ReturnUrl" type="xsd:string" nillable="false"/>
			<xsd:element name="SettlementNRB" type="xsd:string" />
			<xsd:element name="SwiftCode" type="xsd:string" minOccurs="0"/>
			<xsd:element name="ForeignTransferMode" type="tns:ForeignTransferModeType" minOccurs="0"/>
			<xsd:element name="CommissionModel" type="xsd:long" nillable="true"/>
			<xsd:element name="isCardsPaymentRequired" type="xsd:boolean" minOccurs="0" />
			<xsd:element name="AverageServiceTurnover" type="xsd:decimal" minOccurs="0" />
			<xsd:element name="AverageTransactionAmount" type="xsd:decimal" minOccurs="0" />
			<xsd:element name="EconomicPurpose" type="xsd:string" minOccurs="0" />
			<xsd:element name="EconomicPurposeDescription" type="xsd:string" minOccurs="0" />
			<xsd:element name="NumericTrade" type="xsd:int" minOccurs="0" />
			<xsd:element name="InvoiceEmail" type="xsd:string" minOccurs="0" />
			<xsd:element name="ContactEmail" type="xsd:string" minOccurs="0"/>
			<xsd:element name="ComplaintEmail" type="xsd:string" minOccurs="0"/>
			<xsd:element name="ReportEmail" type="xsd:string" minOccurs="0"/>
			<xsd:element name="isTransactionRefundAllowed" type="xsd:boolean" minOccurs="0" />
			<xsd:element name="Currency" type="tns:Currency" minOccurs="0"/>
		</xsd:sequence>
	</xsd:complexType>

Opis pól komunikatu

Company

Typ komunikatu służący do przekazywania danych Partnera.

	<xsd:complexType name="Company">
		<xsd:sequence>
			<xsd:element name="CompanyRemoteId" type="xsd:string"/>
			<xsd:element name="Name" type="xsd:string"/>
			<xsd:element name="Address" type="tns:Address"/>
			<xsd:element name="Nip" type="tns:NIPType"/>
			<xsd:element name="Krs" type="xsd:string"/>
			<xsd:element name="Phone" type="xsd:string"/>
			<xsd:element name="RepresentingPersonFirstName" type="xsd:string"/>
			<xsd:element name="RepresentingPersonLastName" type="xsd:string"/>
			<xsd:element name="RepresentingPersonPesel" type="xsd:string"/>
			<xsd:element name="RepresentingPersonDateOfBirth" type="xsd:string"/>
			<xsd:element name="RepresentingPersonBirthCountry" type="xsd:string" minOccurs="0"/>
			<xsd:element name="RepresentingPersonCitizenship" type="xsd:string"/>
			<xsd:element name="RepresentingPersonPersonalDocumentType" type="xsd:string"/>
			<xsd:element name="RepresentingPersonPersonalDocument" type="xsd:string"/>
			<xsd:element name="RepresentingPersonPersonalDocumentExpirationDate" type="xsd:string"/>
			<xsd:element name="RepresentingPersonPersonalDocumentCountryId" type="xsd:string" minOccurs="0"/>
			<xsd:element name="Service" type="tns:Service"/>
			<xsd:element name="ActivityKind" type="xsd:string"/>
			<xsd:element name="LegalForm" type="xsd:string" minOccurs="0"/>
			<xsd:element name="PanelAdministrator" type="xsd:string" minOccurs="0" />
			<xsd:element name="isListedOnTheStockExchange" type="tns:BooleanType" />
			<xsd:element name="Beneficials" type="tns:Beneficials" minOccurs="0" />
			<xsd:element name="TradeRegisterName" type="xsd:string" minOccurs="0"/>
			<xsd:element name="RegistrationDate" type="xsd:string" minOccurs="0"/>
			<xsd:element name="Plenipotentiary" type="tns:Plenipotentiary" minOccurs="0"/>
			<xsd:element name="Partners" type="tns:Partners" minOccurs="0" />
			<xsd:element name="PhysicalPerson" type="tns:PhysicalPerson" minOccurs="0"/>
		</xsd:sequence>
	</xsd:complexType>

Opis pól komunikatu

PhysicalPerson

Typ komunikatu służący do przekazywania danych osoby fizycznej. Wypełniany, kiedy ActivityKind = NON_ACCOUNTED_ACTIVITY.

	<xsd:complexType name="PhysicalPerson">
		<xsd:sequence>
			<xsd:element name="FirstName" type="xsd:string"/>
			<xsd:element name="LastName" type="xsd:string"/>
			<xsd:element name="Pesel" type="xsd:string"/>
			<xsd:element name="DocumentType" type="xsd:string" minOccurs="0"/>
			<xsd:element name="Document" type="xsd:string"/>
			<xsd:element name="DocumentExpirationDate" type="xsd:string"/>
			<xsd:element name="DocumentCountryId" type="xsd:string" minOccurs="0"/>
			<xsd:element name="Citizenship" type="xsd:string"/>
			<xsd:element name="BirthDate" type="xsd:string" minOccurs="0"/>
			<xsd:element name="BirthCountry" type="xsd:string" minOccurs="0"/>
		</xsd:sequence>
	</xsd:complexType>

Opis pól komunikatu

Zasady weryfikacji na formularzu danych dotyczących beneficjentów

Weryfikacja danych na formularzu odbywa się głównie w oparciu o formę prawną firmy. W zależności od niej oczekiwane są typy beneficjentów, określone są ich wzajemne wykluczenia oraz maksymalna ilość wystąpień dla każdego typu.

Typ beneficjenta jest definiowany na formularzu poprzez zaznaczenie przez Klienta odpowiedniego oświadczenia.

Lista parametrów dla Przelewu weryfikacyjnego

Partner zakładający nowe konto w Systemie zobowiązany jest wykonać Przelew weryfikacyjny. Po jego wykonaniu AP przeprowadza ocenę wiarygodności, prawidłowości danych Partnera oraz ocenę AML.

Kiedy Partner zaktualizuje dane, AP oczekuje wykonania Przelewu weryfikacyjnego – wyłącznie w przypadku wrażliwych i kluczowych danych.

Lista parametrów, dla których rejestracja lub edycja danych serwisu spowoduje wygenerowanie linku Przelewu weryfikacyjnego

Nazwa pola

• Name
• Address
• Email
• Nip
• Krs
• ActivityKind
• ServiceUrl
• SettlementNRB
• NumericTrade
• TradeRegisterName
• RegistrationDate
• SwiftCode
• FirstName
• LastName
• Pesel
• DocumentType
• Document
• DocumentExpirationDate
• DocumentCountryId
• Citizenship
• BirthDate
• BirthCountry

UWAGA: ServiceUrl jest traktowany jako taki sam, jeśli:
a. różni się tylko protokołem (http/https)
b. w trakcie integracji z Partnerem został potwierdzony proces migracji adresu Serwisu z/do subdomeny CMSa Integratora (np. przykladowastrona.integrator.pl = przykladowastrona.pl)
c. została pominięta lub dodana składowa „www" adresu sklepu (np. przykladowastrona.pl = www. przykladowastrona.pl)

UWAGA: NIP, KRS oraz forma prawna są danymi, których nie można edytować. W przypadku konieczności zmiany tych danych należy ponownie zarejestrować Serwis.

Link do przelewu weryfikacyjnego

Link do Przelewu weryfikacyjnego oraz wszystkie jego notyfikacje ITN, zawierają wymieniony podczas integracji dedykowany dla tego procesu ServiceID oraz OrderID zbudowany według schematu:

OrderID = ActivationServiceID_UID

gdzie:

• ActivationServiceID – jest wartością ServiceID weryfikowanego Serwisu
• UID – jest ciągiem znaków, gwarantującym unikalność Przelewu weryfikacyjnego danego Serwisu.
• Wszystkie komunikaty (start oraz powrót z transakcji weryfikacyjnej, a także wszystkie jej notyfikacje ITN, przekazujące informacje o postępie procesu weryfikacji) podpisane są kluczem współdzielonym dla usługi Przelewu weryfikacyjnego (również wymienionym podczas integracji).

WSKAZÓWKA: Parametry ITN dedykowane do procesu weryfikacji opisane są w ramach części Dodatkowe pola w komunikacie ITN/IPN transakcji wejściowej. W szczególności mowa tutaj o polach verificationStatus oraz verificationStatusReasons.

WSKAZÓWKA: Możliwe przejścia statusów płatności, weryfikacji oraz ich szczegółów zawierają części: Szczegółowy opis zmiany statusu weryfikacji – dla transakcji zakończonej poprawnie (wynik pozytywny lub negatywny), Szczegółowy opis zmiany statusu weryfikacji – dla transakcji nie zakończonej poprawnie.

Rejestracja i obsługa Punktów Rozliczeń pomiędzy AP a Platformą Marketplace Partnera

Opis działania usługi automatycznej rejestracji i obsługi Punktów Rozliczeń

Niniejszy dokument opisuje zasady związane z wymianą komunikatów pomiędzy AP, a Platformą Marketplace Partnera w ramach funkcjonalności dodawania Punktów Rozliczeń (technologia REST).

Partner powinien na swojej Platformie Marketplace udostępnić przycisk, którego kliknięcie przez Klienta spowoduje wywołanie w systemie AP metody generującej aktualny link do formularza pozwalającego na rejestrację Punktu Rozliczeń.

Po otrzymaniu wspomnianego linku Platforma Marketplace powinna wykonać automatyczne przekierowanie na formularz znajdujący się pod tym linkiem.

Wypełnienie i wysłanie danych Sklepu przez Klienta spowoduje rejestrację Punktu Rozliczeń w systemie AP oraz zwrócenie strony z podziękowaniem oraz linkiem do weryfikacji online, celem sprawdzenia poprawności wprowadzonych danych. Link weryfikacyjny jest wysyłany również na adres email podany przez Klienta na formularzu.

Po wykonaniu płatności weryfikacyjnej przez Klienta oraz otrzymaniu przez AP niezbędnych danych z Kanału Płatności, Punkt Rozliczeń otrzymuje końcowy status weryfikacji. Jego pozytywna wartość powoduje aktywację Punktu Rozliczeń i gotowość do wykonywania płatności przy jego udziale, a do Klienta zostanie wysłana wiadomość z regulaminem zaakceptowanym przez niego na formularzu rejestracyjnym.

WAŻNE! Produkcyjna wersja usługi znajduje się za firewallem. Dostęp do niej jest przydzielany dla skończonej i zdefiniowanej w trakcie integracji puli IP. Nie dotyczy to środowiska testowego.

WAŻNE! Dla jednej Platformy Marketplace na danym środowisku (test/produkcja) przewidziany jest jeden identyfikator Platformy (MarketplaceID) oraz klucz współdzielony dla usługi rejestracji.

WAŻNE! Niedopuszczalne jest udostępnianie w jakiejkolwiek formie (również w kodzie aplikacji uruchamianej na serwerze osób trzecich) danych autoryzacyjnych do usługi tj. MarketplaceID i klucza współdzielonego.

Dane wymieniane podczas integracji obsługi Punktów Rozliczeń

Dane wymieniane w środowisku testowym

Dane przekazywane w środowisku produkcyjnym

Proces dodawania Punktów Rozliczeń

Opis procesu

Wymiana komunikatów pomiędzy AP, a Serwisem Partnera realizujących funkcjonalności dodawania Punktów Rozliczeń odbywa się za pomocą technologii REST. Wszystkie parametry w komunikatach przekazywane są metodą POST. Protokół rozróżnia wielkość liter, zarówno w nazwach, jak i wartościach parametrów. Wartości przekazywanych parametrów powinny być kodowane w UTF-8.

Pobranie aktywnego linku do formularza rejestracyjnego

Po kliknięciu przez klienta przycisku rejestracji na Platformie Marketplace, na adres https://adres_usługi/api/marketplace/link powinno zostać wysłane odpytanie o aktualny link do formularza rejestracyjnego. Komunikat powinien zostać wysłany z nagłówkiem Content-Type: application/json oraz parametrami wskazanymi w tabeli poniżej:

Opis pól komunikatu

WAŻNE! Kolejność atrybutów do wyliczenia Hash musi być zgodna z ich numeracją.

Przykład wyliczenia Hash dla poniższego komunikatu:

	{
	"marketplaceID":1,
	"messageID":"12345678901234567890123456789000",
	"hash":"wartosc_hash"
	}

gdzie

Hash=SHA256(1|12345678901234567890123456789000|klucz_wspoldzielony) = wartosc_hash

Odpowiedź na żądanie

W odpowiedzi na powyższe żądanie zwracany jest (w tej samej sesji HTTP) komunikat zawierający link do formularza lub w przypadku błędu jego opis wraz ze wskazaniem pola, którego dotyczy.

WAŻNE! Kolejność atrybutów do wyliczenia Hash musi być zgodna z ich numeracją.

UWAGA: Po otrzymaniu przez Platformę Marketplace linku do formularza powinno zostać wykonane automatyczne przekierowanie na tenże formularz.

UWAGA: Każda próba rejestracji powinna być poprzedzona pobraniem linka do formularza.

UWAGA: Link do formularza jest aktywny domyślnie przez 24 godziny (wartość może być zmieniona na prośbę Partnera) od jego wygenerowania. Po upłynięciu tego okresu wyświetlenia formularza rejestracyjnego nie jest możliwe.

Przykłady wymienianych komunikatów podczas pobierania linka do formularza

a) Poprawnie przetworzony request.

REQUEST

	{
	"marketplaceID":1,
	"messageID":"12345678901234567890123456789000",
	"hash":"437c941b5c88b9d0bfa58a1d073d724f55cfed794c1cf9648ba2340c3dcc803f"
	}

RESPONSE

	{
	"link": "https://adres_usługi/marketplace/ee0e88d81c11b110c1a35a740996453d745dcde0be449686be6ec0777a02be5d",
	"messageID": "12345678901234567890123456789000",
	"hash": "d01e20cc8ab2c3fbe907e805329d915a20058e96f1d6d91a863361444cbd6379"
	}

b) MessageID został był już w użyciu, nie jest unikatowy.

REQUEST

	{
	"marketplaceID":1,
	"messageID":"12345678901234567890123456789012",
	"hash":"e43ff5f4b3121d1fd267bd66aaf446b079c28292f2a966e23eb1e8a8c0aaf81a"
	}

RESPONSE

	{
		"errors": [
			{
				"field": "messageID",
				"error": "messageId not unique"
			}
		]
	}

c) Unikatowe MessageID musi mieć 32 znaki.

REQUEST

	{
	"marketplaceID":1,
	"messageID":"1234567890123456789012345678900022222",
	"hash":"dc8d14b5e3491a700e7f2479f8c196cc0db76f41b2b2ffac1f042a6cad1e5914"
	}

RESPONSE

	{
		"errors": [
			{
				"field": "messageID",
				"error": "size must be between 32 and 32"
			}
		]
	}

d) Podany hash jest niepoprawny.

REQUEST

	{
	"marketplaceID":1,
	"messageID":"12345678901234567890123456789001",
	"hash":"dc8d14b5e3491a700e7f2479f8c196cc0db76f41b2b2ffac1f042a6cad1eaaaa"
	}

RESPONSE

	{
		"errors": [
			{
				"field": "hash",
				"error": "Invalid hash"
			}
		]
	}

Dodatkowe rozszerzenia

Alternatywne modele rozpoczęcia transakcji

Preautoryzacja kartowa

Opis ogólny działania usługi preautoryzacji kartowej

Obsługa preautoryzacji kartowej dostarcza funkcjonalność blokowania środków na karcie Klienta na pewien (np. z góry ustalony w trakcie zakładania blokady) czas, a następnie dokonywania obciążenia. Szczególnym przypadkiem jest sytuacja, w której blokada jest zdejmowana bez potrącania jakiejkolwiek kwoty (np. usługa na rzecz klienta nie została wykonana).

Wszystkie te operacje (blokowanie środków, obciążanie, wycofywanie blokady) powinny być zlecone przez API Systemu Płatności Autopay. Jeśli w czasie ważności transakcji zakładającej blokadę, nie nastąpi zlecenie obciążenia karty, System dokonuje zwolnienia środków, powiadamiając o tym fakcie standardowym komunikatem o zmianie statusu transakcji (ITN).

Również pozostałe operacje (skuteczne obciążenie, założenie blokady na karcie oraz jej późniejsze obciążenia) skutkują wysyłką komunikatu ITN. Komunikat ten jest jedyną wiążącą informacją o zmianie statusu transakcji oraz (stosowany wraz z usługą transactionStatus; patrz część Odpytanie o status transakcji), pomaga obsłużyć transakcję nie zrywając sesji z użytkownikiem (nawet w przypadku różnych problemów sieciowych). Synchroniczne potwierdzenia operacji (węzeł confirmation, służą jedynie do prezentowania wstępnej informacji o zleceniu).

Etapy transakcji preautoryzacji kartowej

Założenie blokady na wniosek Partnera

Można wyróżnić 3 podstawowe sposoby zakładania blokady na karcie:

a) Zakładanie blokady podczas autoryzacji płatności jednorazowej (Patrz Schemat A dla Preautoryzacji). Klient wypełnia formatkę kartową, po wystartowaniu transakcji, w której Partner wskazuje w parametrach startowych:

- kartowy kanał płatności (GatewayID=1500) oraz

- chęć zabezpieczenia środków, zamiast obciążenia (Hold=true)

b) Zakładanie blokady podczas inicjowania płatności automatycznej (zapisywania karty w Serwisie lub Aplikacji Mobilnej) (Patrz Schemat B dla Preautoryzacji).

WSKAZÓWKA: Cały cykl i wszystkie zdarzenia płatności automatycznej zgodnie z dokumentacją, zmodyfikowany o moment faktycznego obciążenia karty oraz założenia płatności automatycznej – w modelu preautoryzacji to operacja transactionClear powoduje te zdarzenia.

Klient wypełnia formatkę kartową, po wystartowaniu transakcji, w której Partner wskazuje w parametrach startowych:

- kartowy kanał płatności (GatewayID=1503),

- fakt zaakceptowania regulaminu usługi płatności automatycznej dostarczonego przez AP (RecurringAcceptanceState=ACCEPTED, lub po ustaleniach biznesowych wartości PROMPT/FORCE)

- wybór inicjalizacji płatności automatycznej wraz z potencjalnym obciążeniem karty (RecurringAction=INIT_WITH_PAYMENT)

- chęć zabezpieczenia środków, zamiast obciążenia (Hold=true)

c) Zakładanie blokady z wykorzystaniem wcześniej zapisanej karty (Patrz Schemat C dla Preautoryzacji).

WSKAZÓWKA: Cały cykl i wszystkie zdarzenia płatności automatycznej zgodnie z dokumentacją, zmodyfikowany o moment faktycznego obciążenia karty oraz założenia płatności automatycznej – w modelu preautoryzacji to operacja transactionClear powoduje te zdarzenia.

Klient nie wypełnia formatki kartowej, następuje natomiast backendowa (bez przekierowania) przedtransakcja, w której Partner wskazuje w parametrach startowych:

- kartowy kanał płatności (GatewayID=1503)

- wskazanie wcześniej dodanej karty (ClientHash pochodzący z RPAN)

- wybór metody płatności automatycznej (RecurringAction=MANUAL)

- chęć zabezpieczenia środków, zamiast obciążenia (Hold=true)

Każda z tych metod zakładania blokady skutkuje komunikatem ITN, którego status wskazuje wynik autoryzacji transakcji. Poza standardowymi statusami, w wypadku blokowania środków, System może dostarczyć w ITN status paymentStatus=ON_HOLD, który stanowi potwierdzenie założenia blokady środków na karcie Klienta. Ponadto ITN będzie standardowo zawierać globalny identyfikator transakcji (remoteID), który będzie niezbędny do późniejszego obciążenia założonej blokady.

Obciążenie karty na wniosek Partnera

Opis obciążenia karty na wniosek Partnera

Po założeniu blokady może nastąpić zlecenie przez Partnera obciążenia wcześniej zautoryzowanej karty (Patrz Schemat D dla Preautoryzacji). W tym celu należy wywołać dedykowaną usługę transactionClear (https://{host_bramki}/webapi/transactionClear) z odpowiednimi parametrami. Wszystkie parametry przekazywane są metodą POST (Content-Type: application/x-www-form-urlencoded). Protokół rozróżnia wielkość liter zarówno w nazwach jak i wartościach parametrów. Wartości przekazywanych parametrów powinny być kodowane w UTF-8.

Opis dostępnych parametrów dla obciążenia karty na wniosek Partnera

Potwierdzenie wykonania operacji dla obciążenia karty na wniosek Partnera

Do poprawnego odpytania należy, wraz z przekazywanymi parametrami, przesłać zdefiniowany nagłówek HTTP o odpowiedniej treści. Dołączony nagłówek powinien nosić nazwę 'BmHeader' i posiadać następującą wartość 'pay-bm', w całości powinien prezentować się następująco 'BmHeader: pay-bm'. W przypadku poprawnego komunikatu zwracany jest (w tej samej sesji HTTP) tekst w formacie XML, zawierający potwierdzenie wykonania operacji lub opis błędu.

Struktura potwierdzenia (XML)

	<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
	<balancePayoff>
	<serviceID>ServiceID</serviceID>
	<messageID>MessageID</messageID>
	<remoteOutID>RemoteOutID</remoteOutID>
	<hash>Hash</hash>
	</balancePayoff>

Struktura potwierdzenia (XML)

	<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
	<balancePayoff>
	<balancePointID>BalancePointID</balancePointID>
	<messageID>MessageID</messageID>
	<remoteOutID>RemoteOutID</remoteOutID>
	<hash>Hash</hash>
	</balancePayoff>

Opis zwracanych parametrów dla obciążenia karty na wniosek Partnera

Zwolnienie blokady na wniosek Partnera

Po założeniu blokady może nastąpić zlecenie przez Partnera jej zwolnienia (bez potrącania jakichkolwiek środków) (Patrz Schemat E dla Preautoryzacji). Do tej operacji należy użyć usługi releaseHold (Patrz Anulowanie nieopłaconej transakcji). Po skutecznym zainicjowaniu zwolnienia blokady (poprawnej odpowiedzi na anulowanie transakcji), System asynchronicznie dostarczy ITN z paymentStatus=FAILURE oraz paymentStatusDetails=CANCELLED.

Zwolnienie blokady po przeterminowaniu transakcji

W przypadku bezczynności Partnera (po założeniu blokady) przez ustalony czas ważności transakcji, następuje jej zwolnienie przez System (bez potrącania jakichkolwiek środków) (Patrz Schemat F dla Preautoryzacji). System dokona anulowania transakcji, zdjęcia blokady oraz dostarczy ITN z paymentStatus=FAILURE oraz paymentStatusDetails=CANCELLED.

Schematy dla Preautoryzacji

Schemat A dla Preautoryzacji: Zakładanie blokady podczas autoryzacji płatności jednorazowej

Schemat B dla Preautoryzacji: Zakładanie blokady podczas inicjowania płatności automatycznej (zapisywania karty)

Schemat C dla Preautoryzacji: Zakładanie blokady z wykorzystaniem wcześniej zapisanej karty

Schemat D dla Preautoryzacji: Zlecenie przez Partnera obciążenia wcześniej zautoryzowanej karty

Schemat E dla Preautoryzacji: Zlecenie przez Partnera zwolnienia blokady (bez potrącania środków)

Schemat F dla Preautoryzacji: Zwolnienie blokady przez System (bez potrącania środków)

Przedtransakcja

Opis Przedtransakcji

Przedtransakcja rozszerza standardowy model rozpoczęcia transakcji o obsługę określonych potrzeb:

• zamówienia linku do płatności na podstawie przesłanych parametrów

• obciążenia Klienta (jeśli nie jest wymagana dodatkowa autoryzacja dokonana przez Klienta)

• zweryfikowania poprawności linku płatności, zanim Klient zostanie przekierowany do Systemu – wywołanie powoduje walidację parametrów i konfiguracji Systemu

• skrócenia linka płatności – zamiast kilku/kilkunastu parametrów, link zostaje skrócony do dwóch identyfikatorów

• ukrycia danych wrażliwych parametrów linku transakcji – przedtransakcja odbywa się backendowo, a link do kontynuacji transakcji nie zawiera danych wrażliwych, a jedynie identyfikatory kontynuacji

• użycia SDK mobilnego w wariancie mieszanym – start transakcji wykonuje backend aplikacji mobilnej, a nie samo SDK z użyciem tokena transakcyjnego

WSKAZÓWKA: Szczegóły na temat wariantów SDK w Dokumentacji SDK.

Szczególne przypadki użycia Przedtransakcji, to obciążenia:

• BLIK 0
  Aby użyć tej usługi należy podać GatewayID=509 oraz przekazać kod autoryzacji transakcji w parametrze AuthorizationCode.

• BLIK 0 OneClick

• Obciążenia „Płatności automatycznej"
  Aby użyć tej usługi należy podać jeden z GatewayID o gatewayType="Płatność automatyczna" oraz niezbędne parametry.

• Autoryzacje poprzez portfele Visa
  Aby użyć tej usługi należy podać GatewayID=1511 oraz przekazać zakodowany token w parametrze PaymentToken. W przypadku braku tokena, autoryzacja odbędzie się na stronie Systemu.

• Autoryzacje poprzez portfele Google Pay

UWAGA: Usługa umożliwia obciążenie karty zapisanej w portfelu Klienta bez przekierowania do Systemu. Często następuje wymuszenie dodatkowej autoryzacji w postaci 3DS (domyślne zachowanie środowiska testowego, które można przekonfigurować).

W modelu Whitelabel należy zintegrować się zgodnie z opisem, a następnie podać GatewayID=1512 oraz zakodowany token w parametrze PaymentToken. W przypadku braku tokena (lub model inny, niż Whitelabel) wystarczy podać GatewayID=1512 - autoryzacja odbędzie się na stronie Systemu.

• Autoryzacje poprzez portfele Apple Pay
  Aby użyć tej usługi należy podać GatewayID=1513. Autoryzacja odbędzie się na stronie Systemu.

• Autoryzacja poprzez natywną formatkę SDK mobilnego

UWAGA: Usługa umożliwia obciążenie karty, której szczegóły podano na bezpiecznej formatce kartowej SDK, a sam start transakcji wykonuje backend aplikacji mobilnej.

Oprócz odpowiedniego GatewayID - 1500 dla płatności jednorazowej lub 1503 dla aktywacji płatności automatycznej (oraz innych parametrów) – należy podać uzyskany z SDK PaymentToken oraz parametr WalletType=SDK_NATIVE (opis w części Rozpoczęcie transakcji z dodatkowymi parametrami)

Wywołanie Przedtransakcji

Obowiązkowym elementem w przypadku przedtransakcji jest przesłanie backendowo (używając np. cURL) standardowego komunikatu startu transakcji (patrz Rozpoczęcie transakcji), z nagłówkiem 'BmHeader' o wartości: 'pay-bm-continue-transaction-url':

Przykład nagłówka

'BmHeader: pay-bm-continue-transaction-url')

Dodatkowo zalecane jest przekazywanie parametru CustomerIP (do celów reklamacyjnych, sprawozdawczych).

Przykład startu Przedtransakcji (PHP)

	$data = array(
	 'ServiceID' => '100047',
	 'OrderID' => ‘20161017143213’,
	 'Amount' => '1.00',
	 'Description' => 'test bramki',
	 'GatewayID' => '0',
	 'Currency' => 'PLN',
	 'CustomerEmail' => 'test@bramka.pl',
	 'CustomerIP' => '127.0.0.0',
	 'Title' => 'Test title',
	'Hash' => 0c5ca136e8833e40efbf42a4da7c148c50bf99f8af26f5c9400681702bd72056
	);

	$fields = (is_array($data)) ? http_build_query($data) : $data;

	$curl = curl_init('https://{host_bramki}/test_ecommerce');
	curl_setopt($curl, CURLOPT_HTTPHEADER, array('BmHeader: pay-bm-continue-transaction-url'));
	curl_setopt($curl, CURLOPT_POSTFIELDS, $fields);
	curl_setopt($curl, CURLOPT_POST, 1);
	curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
	curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, true);
	$curlResponse = curl_exec($curl);
	$code = curl_getinfo($curl, CURLINFO_HTTP_CODE);
	$response = curl_getinfo($curl);
	curl_close($curl);

	echo htmlspecialchars_decode($curlResponse);

Odpowiedź na Przedtransakcję – link do kontynuacji transakcji

W przypadku poprawnej walidacji parametrów (i konfiguracji) oraz potrzeby wykonania przez Klienta dodatkowej akcji (wybrania kanału płatności - jeśli podano GatewayID=0, wykonania/zatwierdzenia przelewu, podania kodu CVC/CVV, wykonania 3DS) – zostanie zwrócony XML z linkiem kontynuacji transakcji.

Przykład pliku z linkiem kontynuacji transakcji (XML)

	<?xml version="1.0" encoding="UTF-8"?>
		<transaction>
		<status>PENDING</status>
		<redirecturl>
		https://{host_bramki}/payment/continue/96VSD39Z6E/L6CGP5BH
		</redirecturl>
		<orderID>20180824105435</orderID>
		<remoteID>96VSD39Z6E</remoteID>
		<hash>
		1c6eae2127f0c3f81fbed3b6372f128040729a4d4e562fb696c22e0db68dbbe1
		</hash>
	</transaction>

Obiekt transaction dla Przedtransakcji

Obiekt transaction reprezentuje wpływ lub wypłatę środków z konta AP, np. zrealizowany zakup lub zwrot.

Atrybuty obiektu transaction dla Przedtransakcji

WAŻNE! Kolejność atrybutów do wyliczenia Hash musi być zgodna z ich numeracją.

Odpowiedź na Przedtransakcję – brak kontynuacji transakcji

W przypadku niepoprawnej walidacji lub nieskutecznego obciążenia nie jest generowany link kontynuacji. Zwracany jest (w tej samej sesji HTTP) tekst w formacie XML, informujący o statusie przetwarzania żądania.

Przykład statusu przetwarzania żądania (XML)

<?xml version="1.0" encoding="UTF-8"?>
<transaction>
	<orderID>OrderID</orderID>
	<remoteID>RemoteID</remoteID>
	<confirmation>ConfStatus</confirmation>
	<reason>Reason</reason>
	<blikAMList>
		<blikAM>
			<blikAMKey>Klucz1</blikAMKey>
			<blikAMLabel>Etykieta1</blikAMLabel>
		</blikAM>
		<blikAM>
			<blikAMKey>Klucz2</blikAMKey>
			<blikAMLabel>Etykieta2</blikAMLabel>
		</blikAM>
	</blikAMList>
	<paymentStatus>PaymentStatus</paymentStatus>
	<hash>Hash</hash>
</transaction>

Wynik Przedtransakcji

Parametry zwracane dla wyniku Przedtransakcji.

WAŻNE! Kolejność atrybutów do wyliczenia Hash musi być zgodna z ich numeracją.

	<blikAM>
	<blikAMKey>Klucz1</blikAMKey>
	<blikAMLabel>Etykieta1</blikAMLabel>
	</blikAM>
	…
	<blikAM>
	<blikAMKey>KluczN</blikAMKey>
	<blikAMLabel>EtykietaN</blikAMLabel>
	</blikAM>

Poprawna walidacja parametrów

W przypadku poprawnej walidacji parametrów (i konfiguracji) oraz braku potrzeby wykonania przez Klienta dodatkowej akcji – zwracane jest potwierdzenie zlecenia obciążenia.

Ma to miejsce w przypadkach, gdzie dane są wystarczające do wykonania obciążenia dla danego kanału płatności, na przykład: BLIK 0 bez wymaganego kodu BLIK (ani wskazania aliasu aplikacji mobilnej banku), płatność cykliczna, płatność Kartą OneClick bez wymaganego CVC/CVV/3DS.

Result

confirmation=CONFIRMED

Niepoprawna walidacja parametrów

W przypadku niepoprawnej walidacji parametrów (i konfiguracji) – zwracany jest błąd.

Result

confirmation=NOTCONFIRMED

Błąd może być również zwrócony w przypadku synchronicznej odpowiedzi z Kanału Płatności (np. błąd specyficzny dla próby inicjalizacji płatności automatycznej BLIK, tj. reason= RECURRENCY_NOT_SUPPORTED).

UWAGA: Błąd może być również zwrócony w przypadku synchronicznej odpowiedzi z Kanału Płatności (np. błąd specyficzny dla próby inicjalizacji płatności automatycznej BLIK, tj. reason=RECURRENCY_NOT_SUPPORTED). Innym znanym przypadkiem jest też błąd walidacji adresu podanego w parametrze startowym CustomerEmail (INVALID_EMAIL).

Obsługa odpowiedzi dla Przetransakcji

Zamówienie danych do przelewu w transakcji typu Szybki Przelew

Opis zamawiania danych do przelewu w transakcji typu Szybki Przelew

Szybki Przelew to forma płatności, która wymaga od Klienta samodzielnego przepisania danych do przelewu dostarczanych przez System. Jakiego typu jest dany Kanał płatności, mówi parametr gatewayType w odpowiedzi na wywołanie usługi „Odpytywanie o listę aktualnie dostępnych Kanałów Płatności". Dane do przelewu mogą być Klientowi wyświetlone:

• na stronie AP (realizacja transakcji w oparciu o standardowy model startu transakcji opisany w części Rozpoczęcie transakcji)

• w serwisie Partnera (realizację transakcji bez przekierowania Klienta na stronę AP opisano poniżej)

Wywołanie

Dla poprawnego nadania komunikatu należy przesłać backendowo (np. cURLem) standardowy komunikat startu transakcji, z nagłówkiem 'BmHeader' o wartości: 'pay-bm' (w całości nagłówek powinien prezentować się następująco 'BmHeader: pay-bm'). W przypadku błędnego zdefiniowania nagłówka lub jego braku, komunikat zostanie błędnie odczytany. Dodatkowo zalecane jest przekazywanie parametru CustomerIP zgodnie z opisem w punkcie IP użytkownika (potrzebne do procesów reklamacyjnych, sprawozdawczych) oraz wymagane jest przekazanie niezerowego parametru GatewayID (o gatewayType „Szybki Przelew").

Implementacja startu transakcji w tle (PHP)

	$data = array(
	 'ServiceID' => '100047',
	 'OrderID' => '20150723144517',
	 'Amount' => '1.00',
	 'Description' => 'test bramki',
	 'GatewayID' => '71',
	 'Currency' => 'PLN',
	 'CustomerEmail' => 'test@bramka.pl',
	 'CustomerIP' => '127.0.0.0',
	 'Title' => 'Test title',
	 'ValidityTime' => '2016-12-19 09:40:32',
	 'LinkValidityTime' => '2016-07-20 10:43:50',
	 'Hash' => 'e627d0b17a14d2faee669cad64e3ef11a6da77332cb022bb4b8e4a376076daaa'
	);

	$fields = (is_array($data)) ? http_build_query($data) : $data;

	$curl = curl_init('https://{host_bramki}/test_ecommerce');
	curl_setopt($curl, CURLOPT_HTTPHEADER, array('BmHeader: pay-bm'));
	curl_setopt($curl, CURLOPT_POSTFIELDS, $fields);
	curl_setopt($curl, CURLOPT_POST, 1);
	curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
	curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, true);
	$curlResponse = curl_exec($curl);
	$code = curl_getinfo($curl, CURLINFO_HTTP_CODE);
	$response = curl_getinfo($curl);
	curl_close($curl);

	echo htmlspecialchars_decode($curlResponse);

Odpowiedź – dane do przelewu

W przypadku płatności tego typu, System generuje komplet danych potrzebnych do wykonania wewnątrzbankowego (a więc szybkiego) przelewu na rachunek bankowy AP. Dane te umieszczane są w odpowiedzi na start transakcji, w dokumencie xml.

Odpowiedź systemu płatności na start transakcji (XML)

	<?xml version="1.0" encoding="UTF-8"?>
	<transaction>
		<receiverNRB>47 1050 1764 1000 0023 2741 0516</receiverNRB>
		<receiverName>Autopay</receiverName>
		<receiverAddress>81-718 Sopot, ul. Powstańców Warszawy 6</receiverAddress>
		<orderID>9IMYEH2AV3</orderID>
		<amount>1.00</amount>
		<currency>PLN</currency>
		<title>9IMYEH2AV3  - weryfikacja rachunku</title>
		<remoteID>9IMYEH2AV3</remoteID>
		<bankHref>https://ssl.bsk.com.pl/bskonl/login.html</bankHref>
		<hash> fe685d5e1ce904d059eb9b7532f9e06a64c34c1ea9fcf29b62afefdb7aad7b75 </hash>
	</transaction>

Lista zwracanych parametrów dla odpowiedzi

WAŻNE! Kolejność atrybutów do wyliczenia Hash musi być zgodna z ich numeracją.

UWAGA: Powyższe informacje należy wykorzystać do wyświetlenia danych przelewowych oraz przekierowania użytkownika do strony logowania banku.

Płatność BLIK 0 OneClick

Opis płatności BLIK 0 OneClick

Jest to rozwiązanie dedykowane dla płatności BLIK, pozwalające zrealizować płatność bez podawania kodu BLIK (oraz bez konieczności opuszczania Serwisu). Jej skuteczne zainicjowanie w Systemie powoduje automatyczne uruchomienie/wybudzenie aplikacji mobilnej banku i zaprezentowanie transakcji do potwierdzenia Użytkownikowi.

Potencjalne korzyści:

• udostępnienie pierwszej wygodnej i bezpiecznej metody płatności w mCommerce niewymagającej podania numeru karty otwiera ten segment na nowych klientów,

• lepsze doświadczenie zakupowe Klienta - płaci szybciej i wygodniej,

• częstotliwość zakupów i wartość klienta w czasie – Klienci chętniej i częściej kupują w tych sklepach, w których proces zakupowy jest wygodniejszy,

• współczynnik konwersji – Serwis ma większą kontrolę nad procesem zakupu i płatności (Klient go nie opuszcza), eliminowane jest ryzyko utraty koszyka,

• szybka decyzja transakcyjna - w krótkim czasie transakcja podlega autoryzacji, odmowie lub unieważnieniu,

• Serwis ma możliwość objęcia analizą samego etapu dokonywania płatności.

Warunkiem udostępnienia Klientowi BLIK 0 OneClick jest zautoryzowanie w Serwisie (posiadanie konta oraz wcześniejsze do niego zalogowanie). Jeśli podczas wcześniej wykonywanej płatności BLIK, wraz z innymi informacjami o płatności, Serwis przesłał dedykowany Alias UID (opis parametrów BlikUIDKey oraz BlikUIDLabel w innej części dokumentu), a Klient potwierdzając płatność w aplikacji mobilnej zaznaczył, że chce zapamiętać sklep, to skutkiem było trwałe powiązanie (typowo na okres 2 lat) Klienta Serwisu z jego aplikacją, czyli zarejestrowanie Aliasu UID. Kolejne jego użycie będzie skutkować autoryzacją transakcji bez podania kodu.

Wywołanie płatności BLIK 0 OneClick

Zaleca się, aby przy wyborze Kanału Płatności BLIK nie wymuszać podania kodu BLIK. Warto natomiast wyświetlić hiperłącze „Chcę wprowadzić kod BLIK" pod przyciskiem „Kupuję i płacę", aby umożliwić wpisanie kodu w pierwszej próbie (na wypadek, gdyby Klient chciał dokonać płatności BLIK z innej aplikacji mobilnej niż ta, w której wcześniej zapamiętał dany Serwis).

Serwis powinien wykonać Przedtransakcję, ze zwróceniem szczególnej uwagi na:

• podanie parametru GatewayID = 509 – wskazanie kanału płatności BLIK,

• podanie parametrów BlikUIDKey oraz BlikUIDLabel – wskazanie wymaganego w usłudze BLIK 0 OneClick Alias UID (identyfikatora użytkownika)

• podanie parametru AuthorizationCode – jeśli Klient podał kod BLIK,

• podanie parametru BlikAMKey – jeśli Klient wskazał etykietę aplikacji mobilnej banku spośród zaprezentowanej w Serwisie listy,

• obsługę możliwych odpowiedzi na przedtransakcję, w tym obsłużyć „Odpowiedź – brak kontynuacji" oraz błędy specyficzne dla BLIK 0 OneClick:

a) błąd wielu aplikacji mobilnych banku (confirmation=NOTCONFIRMED oraz reason=ALIAS_NONUNIQUE) – wyświetlenie listy etykiet zwróconej w przedtransakcji listy aliasów (pary klucz + etykieta zawarte w strukturze BlikAMList), w celu pobrania wybranego klucza i podania go w parametrze BlikAMKey kolejnej próby przedtransakcji

b) błędy autoryzacji (confirmation=NOTCONFIRMED oraz reason o jednej z wartości: ALIAS_DECLINED, ALIAS_NOT_FOUND, WRONG_TICKET, TICKET_EXPIRED, TICKET_USED) – wyświetlenie pola Kod Blik, w celu pobrania go i podania w parametrze AuthorizationCode kolejnej próby przedtransakcji

Przelewy do Urzędu Skarbowego

Opis

System umożliwia realizację przelewów do Urzędu Skarbowego.

Walidacja tytułów przelewów do Urzędu Skarbowego

nazwa walidatora: US_TITLE_VALIDATOR

Title="/TI/______________/OKR/______/SFP/_______/TXT/_________{idtransremote_out}", gdzie:

a) TI: oznacza identyfikator podatnika (P dla PESEL lub N dla NIP lub R dla REGON). Wpływa na:

• Y w NRB (0/1)
• X w NRB, który jest PESELem, lub NIPem.

b) OKR: Rok, typ okresu i numer okresu, za który dokonywana jest płatność podatku

• R – rok w formacie dwucyfrowym
• P - półrocze
• K - kwartał
• M - miesiąc
• D - dekada
• J - dzień
• 0 (zero) - dla należności niezwiązanych z okresem rozliczeniowym

Numer okresu:

• dla R znaki 4-7 nie powinny być wypełnione
• dla P znaki 4-5 = 01 lub 02, znaki 6-7 nie wypełnione
• dla K znaki 4-5 = 01,02,03 lub 04, znaki 6-7 nie wypełnione
• dla M znaki 4-5 = 01 do 12, znaki 6-7 nie wypełnione
• dla D znaki 4-5 = 01,02 lub 03, znaki 6-7 = 01 do 12
• dla J znaki 4-5 = 01 do 31, znaki 6-7 = 01 do 12

c) SFP: symbol formularza płatności:

d) TXT: dodatkowy tekst (max 29 znaków)

e) {idtransremote_out} → stała tytułu, która musi znajdować się na końcu ciągu. W to miejsce nie należy wklejać żadnych dodatkowych wartości.

Google Pay

Opis

Google Pay to błyskawiczny i intuicyjny system płatności od Google. Pozwala on użytkownikowi na przeprowadzenie procesu płatności bez wypełniania formularza kartowego, ponieważ dane karty są przechowywane bezpiecznie na serwerach firmy.

Google Pay to produkt umożliwiający uzyskanie zaszyfrowanych danych karty płatniczej klienta pozwalających na jej obciążenie.

W celu dokonania płatności przez Google Pay należy zapisać kartę płatniczą na swoim koncie Google, używając jakiejkolwiek platformy Google (np. kupując aplikacje w Google Play) lub bezpośrednio na stronie Google Pay.

UWAGA: Usługa wymaga wcześniejszego podpisania umowy z operatorem kartowym. Po szczegółowe informacje należy zwrócić się do Działu Biznesu Autopay.

Schemat komunikacji

Po kliknięciu „Zapłać przez Google Pay" na stronie sklepu pojawia się formularz Google Pay. Klient potwierdza w nim swoje konto Google i kartę, którą zamierza zapłacić (na tym etapie może też zmienić kartę na inną lub dodać nową). Skrypt przekazuje zakodowane dane karty w tle poprzez funkcję postMessage, następnie sklep musi je przyjąć i zakodować przez funkcję base64 i w końcu wysłać w parametrze PaymentToken wraz z pozostałymi parametrami (danymi transakcji).

Na swojej stronie sklep musi wywołać skrypt udostępniony przez Google z podmienionymi danymi Procesora płatności.

WSKAZÓWKA: Szczegóły w dokumentacji deweloperskiej Google.

Szczegółowy schemat komunikacji i wymiany danych

Rejestracja Transakcji Google Pay

1. Sklep na swojej stronie musi wysłać zapytanie do Systemu Płatności Online AP, aby pobrać dane potrzebne do realizacji płatności Google Pay (paybmApiResponse).

WSKAZÓWKA: Przykład wysłania zapytania dostępny jest na GitHubie Autopay.

2. Następnie, sklep musi wywołać skrypt udostępniony w części Samouczek dokumentacji deweloperskiej Google, zawierający:

a) Podmienione dane Procesora płatności:

const tokenizationSpecification = {
	type: 'PAYMENT_GATEWAY',
	parameters: {
		'gateway': 'bluemedia',
		'gatewayMerchantId': paybmApiResponse.acceptorId
	}
};

b) Dane zwrócone przez System Płatności Online AP przekazane w obiekcie PaymentDataRequest.merchantInfo:

PaymentDataRequest.merchantInfo = {
	merchantId: paybmApiResponse.merchantId,
	merchantOrigin: paybmApiResponse.merchantOrigin,
	merchantName: paybmApiResponse.merchantName,
	authJwt: paybmApiResponse.authJwt,
};

3. Po kliknięciu „Zapłać przez Google Pay" na stronie sklepu pojawia się formularz Google Pay. Klient potwierdza w nim swoje konto Google i kartę, którą ma zamiar zapłacić (na tym etapie może też zmienić kartę na inną lub dodać nową). Skrypt w tle przekazuje zakodowane dane karty, które sklep musi przyjąć, a następnie zakodować funkcją Base64 i wysłać w parametrze PaymentToken wraz z pozostałymi parametrami startowymi transakcji (tj. danymi transakcji Systemu Płatności Online AP - szczegóły opisane są w części Rozpoczęcie transakcji z dodatkowymi parametrami).

WSKAZÓWKA: Kompletny przykład integracji z Google Pay dostępny jest na GitHubie Autopay.

Informację dodatkowe

Aby zachować integralność estetyczną stylistyki stosowanej na stronie www oraz w aplikacji mobilnej należy skorzystać ze wskazówek, które znajdują się w części Brand Guidelines dokumentacji deweloperskiej Google w przypadku opisów styli oraz przycisków dla stron www, oraz w części Tutorial dokumentacji deweloperskiej Google, gdzie znajdują się informacje potrzebne przy tworzeniu aplikacji mobilnej.

Apple Pay

Implementacja Apple Pay na stronie sklepu.

Prośba o kontakt z produktem infrastruktury płatniczej - potrzebne wsparcie IT.

1. Utworzenie konta przez Partnera i uzyskanie certyfikatu przetwarzania płatności zgodnie z dokumentem Configure Apple Pay (iOS, watchOS)

 - certyfikat komunikacyjny – do tzw. przedstawienia się – merchant identifier

 - certyfikat obciążający – payment processing certificate

2. Implementacja Web zgodnie z dokumentem Apple Pay on the Web

3. Przygotowanie 2 końcówek po stronie Partnera, w domenie zgłoszonej w Apple (z wykorzystaniem 2 certyfikatów od Apple):

 - do rozpoczęcia sesji

 - do obciążenia Klienta na podstawie tokena od Apple

WSKAZÓWKA: safari (przeglądarka Klienta) puka o sesję do końcówki (o której mowa powyżej) oni wtedy trafiają do nas - my zwracamy sesję.

4. Przetwarzanie płatności Apple Pay

• W ramach rejestracji usługi w Apple wygenerować swój certyfikat merchant identity.
• Wygenerować certyfikat payment processing na bazie certyfikatu dostarczonego przez AP CSR

UWAGA: Certyfikaty AP CSR dla acceptu i dla produkcji różnią się).

• Po wykorzystaniu go w procesie rejestracji Apple dostarczyć AP certyfikat podpisany przez Apple i wysłać poprzez formularz Autopay

  WSKAZÓWKA: Klient powinien podać kraj, miasto, domenę strony www, email osoby kontaktowej.

• W ramach realizacji płatności na stronie Partnera, rozpocząć sesję API Apple.

• Następnie zwrócić Autopay token w parametrze startowym PaymentToken.

UWAGA: Odszyfrowanie tokena to obowiązek AP.

Format payment tokena: wycinek obiektu w formacie json, który zwraca api ApplePay:

  EncryptedPaymentData {
	  String version;
	  String data;
	  String signature;
	  Header header;
  }
  Header {
	  String ephemeralPublicKey;
	  String publicKeyHash;
	  String transactionId;
	  String applicationData;
  }
  

UWAGA: Przy wysyłce ApplePayPaymentRequest, trzeba uzupełnić pole applicationData o wartość orderId zakodowaną Base64, zgodnie z opisem w dokumencie applicationData.

Płatność kartą osadzoną w Serwisie (iFrame)

Opis płatności kartą osadzoną w Serwisie (iFrame)

Jest to rozwiązanie dedykowane dla płatności kartą, pozwalające w prosty sposób zrealizować płatność bez konieczności opuszczania Serwisu.

WAŻNE! Partner nie jest upoważniony do przechowywania danych Karty (w szczególności numeru karty, kodu zabezpieczającego CVC, CVV2), z wyjątkiem parametrów przekazywanych przy realizacji płatności automatycznych przez AP, opisanych w tej części.

WAŻNE! Serwis Partnera w którym wykorzystywana jest funkcjonalność iFrame musi być szyfrowana a iFrame musi być osadzony na adresie HTTPS z użyciem protokołu TLS.

WAŻNE! Partner zobowiązuje się przedłożyć AP, w formie elektronicznej, następujące dokumenty:
a) jednorazowo (przed zawarciem Umowy): wypełniony kwestionariusz SAQ-A PCI (Section 2); Dokument zostanie dostarczony przez AP lub jest możliwy do pobrania na stronie: https://www.pcisecuritystandards.org
b) kwartalnie: wynik kwartalnego audytu PCI ASV obejmującego skanowanie zewnętrznych (publicznych) adresów IP/sieci/domen – protokołu IPv4 oraz/lub IPv6. Audyt taki musi zostać przeprowadzony przez jednego z autoryzowanych wykonawców, z listy dostępnej pod adresem: https://www.pcisecuritystandards.org/assessors_and_solutions/approved_scanning_vendors

Wyróżniamy dwie metody integracji z Systemem:

1. (Rekomendowana) W oparciu o funkcję Przedtransakcji,

2. Z wykorzystaniem klasycznego modelu startu transakcji opisanego szczegółowo w części Rozpoczęcie transakcji. W przypadku tej metody integracji należy pamiętać o nieupublicznianiu Klucza współdzielonego Serwisu, który służy do wyliczenia Hash (również w formie elementów ukrytych HTML/JS). Model ten nie może być wykorzystany do kolejnych obciążeń Karty typu OneClick (ze względu na potrzebę podania parametru ClientHash, który jest traktowany, jako dana wrażliwa).

UWAGA: W obydwu przypadkach należy upewnić się, że ustawione są poniższe parametry startu transakcji:
- ScreenType=IFRAME
- GatewayID=1500 lub 1503 (automatyczna płatność jednym kliknięciem lub cykliczna)
iFrame może mieć zastosowanie podczas aktywacji usługi oraz płatności OneClick, jeśli wymagany jest CVC/CVV (Płatność automatyczna).

Procedura obsługi kart w Serwisie (iFrame)

Poniżej lista czynności do wykonania, aby obsłużyć iFrame kartowy:

1. Załączyć bibliotekę

   https://{host_kartowy_bramki}/integration/checkout.js

2. Zaimplementować obsługę 3 funkcji zwrotnych (patrz Obsługa funkcji zwrotnych)

a) Transakcja zakończona pozytywnie:

		PayBmCheckout.transactionSuccess = function (status) {
			console.log('transactionSuccess');
			console.log(status);
		}; 	

b) Transakcja odrzucona bądź iFrame zamknięty przez zakończeniem transakcji:

		PayBmCheckout.transactionDeclined = function (status) {
			console.log('transactionDeclined');
			console.log(status);
		};

c) Błąd przetwarzania żądania:

		PayBmCheckout.transactionError = function (status) {
			console.log('transactionError');
			console.log(status);
		};

3. Zainicjować transakcję

a) preferowana metoda - za pomocą linka uzyskanego wcześniej w Przedtransakcji (przykład: https://jsfiddle.net/5ohpvLqy/15/)

		$('button').click(function() {
			PayBmCheckout.transactionStartByUrl("<url kontynuacji transakcji>");
		});

b) za pomocą parametrów (przykład: https://jsfiddle.net/5ohpvLqy/25/)

		...
		<form method="POST" action="<https://{host_bramki}/sciezka>">
			<input type="hidden" name="ServiceID" value="12345"/>
			<input type="hidden" name="OrderID" value="aaaabbbbccc"/>
			<input type="hidden" name="Amount" value="10.00"/>
			<input type="hidden" name="GatewayID" value="1500"/>
			<input type="hidden" name="ScreenType" value="IFRAME"/>
			...
			<input type="hidden" name="Hash" value="aaabbbcccddddeee"/>

			<button>submit</button>
		</form>

		<script>
		PayBmCheckout.actionURL = $('form').attr('action');
		$('button').click(function() {
			var formParamsArray = $('form').serializeArray();
			var params = {};
			for (var i = 0; i < formParamsArray .length; i++){
				params[formParamsArray[i]['name']] = formParamsArray[i]['value'];
			}
			PayBmCheckout.transactionStartByParams(params);
			return false;
		});
		</script>

Obsługa funkcji zwrotnych

Każdy callback wywoływany jest z parametrem opisującym status transakcji. Znaczenie statusu jest informacyjne (nie księgowe) i służy do dostosowania komunikatu i ewentualnych przekierowań w Serwisie. Można przykładowo wyświetlić potwierdzenie płatności, ale procesy biznesowe (wysyłka produktu, wykonanie usługi) powinny być wstrzymane do potwierdzenia w ITN.

Przykładowy parametr status (JSON)

	status = {
		message: "opis słowny (opcjonalnie)",
		status: "KOD_STATUSU"
	}

Kody błędów przekazywanych do sklepu

UWAGA: Część błędów jest niezależna od Partnera (np. DECLINED, BANK_DISABLED).
Pozostałe błędy mogą wynikać z błędów integracji między Systemem a Serwisem i należy je poprawić:
- BLOCK_MULTIPLE_TRANSACTIONS – Serwis nie zachowuje unikalności OrderID (i System rygorystycznie przestrzega tego ograniczenia)
- BLOCK_PAID_TRANSACTIONS – Serwis nie zachowuje unikalności OrderID (i zarejestrowana wcześniej transakcja jest już opłacona)
- INSUFFICIENT_START_AMOUNT – kwota jest zbyt mała (niepoprawna wartość pola Amount)
- OUTDATED_ERROR – transakcja jest przeterminowana (niepoprawna wartość pola ValidityTime lub LinkValidityTime lub wykorzystano link z przeterminowanej przedtransakcji)
- PAYWAYLIST_LOADED – nie określono prawidłowego kanału płatności (GatewayID nie wskazuje na karty)

Płatność automatyczna

Opis płatności automatycznej

Płatności automatyczne to wyjątkowo wygodny i bezpieczny sposób dokonywania powtarzalnych transakcji. Polega ona na automatycznym pobieraniu należności od Klienta w jej terminach płatności. Usługę należy najpierw aktywować. W przypadku kart odbywa się to poprzez przekierowanie klienta do formatki aktywacyjnej usługi. W przypadku BLIK natomiast poprzez akceptację płatności automatycznej w Aplikacji Mobilnej. Po skutecznym zautoryzowaniu takiej transakcji aktywacyjnej, AP przekazuje do Partnera standardowy komunikat o zmianie statusu transakcji (ITN) oraz komunikat o uruchomieniu usługi płatności automatycznej (RPAN). Komunikat RPAN zawiera pole clientHash, którym Partner będzie identyfikować konkretną płatność automatyczną podczas późniejszych obciążeń oraz dezaktywacji usługi.

Wszystkie transakcje w ramach cyklu życia płatności automatycznej (aktywacja i obciążenia) są realizowane w ramach dedykowanych Kanałów Płatności (BLIK – GatewayID=522, Karty – GatewayID = 1503) o gatewayType="Płatność automatyczna". W przypadku integrowania płatności automatycznej BLIK, można podać (w danych podawanych przed integracją) długość życia aktywowanych płatności automatycznych (domyślnie bezterminowe) lub podawać ją w transakcji inicjalizującej (parametr RecurringValidityTime).

Aktywacja płatności automatycznej

Aktywacja płatności automatycznej składa się z autoryzacji transakcji aktywacyjnej, komunikacji ITN oraz RPAN. Po otrzymaniu RPAN, Partner jest gotowy do wykonywania obciążeń cyklicznych (lub jednym kliknięciem).

Jest to przypadek aktywacji usługi płatności automatycznej podczas płatności za usługę/towar (a więc RecurringAction=INIT_WITH_PAYMENT i rozliczenie transakcji do Partnera).

Proces aktywacji usługi płatności automatycznych

Komunikat ITN wysyłany po płatności automatycznej jest podobny do tych, otrzymywanych po płatnościach jednorazowych (rozszerzony jest jedynie o węzeł RecurringData, oraz - dla płatności kartowej – CardData). Pozostałe dwa elementy procesu aktywacji usługi to start transakcji oraz RPAN.

Komunikat startu transakcji automatycznej

Proces aktywacji usługi inicjowany jest z Serwisu Partnera, poprzez rozpoczęcie transakcji z parametrem RecurringAction pozwala sterować zachowaniem Systemu:

a) wartość INIT_WITH_PAYMENT - odpowiada aktywacji usługi płatności automatycznej podczas płatności za usługę/towar (karta lub rachunek obciążane są kwotą należności, a środki z płatności przekazywane są do Partnera); na liście dostępnych kanałów płatności System prezentuje tylko płatności automatyczne (o ile nie wybrano kanału płatności w Serwisie),

b) wartość INIT_WITH_REFUND – odpowiada aktywacji usługi płatności automatycznej poza procesem płatności za usługę/towar (karta lub rachunek obciążane są kwotą 1 PLN, po czym następuje automatyczny zwrot środków na rachunek Klienta); na liście dostępnych kanałów płatności System prezentuje tylko płatności automatyczne (o ile nie wybrano kanału płatności w Serwisie),

c) brak parametru (lub pusty) – o ile nie wybrano kanału płatności w Serwisie, System wyświetli wszystkie dostępne dla Serwisu kanały płatności (wraz z automatycznymi) oraz pozostawi Klientowi decyzję: płatność jednorazowa, czy uruchomienie płatności automatycznej. Jeśli Klient wybierze płatność automatyczną, to transakcja zostanie w standardowy sposób rozliczona na rzecz Partnera (a w RPAN wróci parametr RecurringAction=INIT_WITH_PAYMENT).

UWAGA: Niedozwolone jest rozpoczynanie transakcji aktywacyjnych z wybranym kanałem płatności automatycznej, ale bez wybranego RecurringAction.

W niektórych przypadkach (jeśli wynika to z odpowiedzi metody legalData) wymagane jest również podanie parametrów RecurringAcceptanceState (o wartości ACCEPTED, co oznacza to, że Klient przeczytał i zaakceptował regulamin płatności automatycznej na Serwisie Partnera) oraz RecurringAcceptanceID.

Aktywacja usługi kartowej płatności automatycznej odbywa się na formatkach dostarczanych przez AP. Klient jest zobowiązany do podania danych karty: Imię, Nazwisko, Numer karty, Datę ważności oraz kod CVV. W przypadku automatycznej płatności z rachunku bankowego (BLIK), autoryzacja następuje bez podawania danych kartowych: np. kodem BLIK (transportowanym w parametrach startowych w AuthorizationCode), lub poprzez Alias BLIK OneClick (transportowanym w parametrach startowych w BlikUIDKey/BlikUIDLabel).

Po zautoryzowaniu transakcji, System AP przekazuje do Serwisu Partnera komunikat o zmianie statusu transakcji (ITN) oraz komunikat o uruchomieniu usługi płatności automatycznej (RPAN). Komunikat RPAN jest dedykowany dla zdarzeń aktywacji płatności automatycznej i zawiera jej identyfikator (ClientHash), którym Partner będzie się posługiwać podczas późniejszych obciążeń oraz dezaktywacji usługi. RPAN zawiera też informację o akcji w procesie płatności automatycznej (RecurringAction, opisany wyżej).

Powiadomienie o uruchomieniu płatności automatycznej (RPAN)

Po otrzymaniu pozytywnego statusu płatności dla aktywacji płatności automatycznej, wysyłany jest do Serwisu dedykowany komunikat. Powiadomienie to polega na wysłaniu przez System AP dokumentu XML zawierającego dane o uruchomionej płatności automatycznej. Dokument wysyłany jest protokołem HTTPS (domyślnie port 443), metodą POST, jako parametr HTTP o nazwie recurring. Parametr ten jest zapisany mechanizmem kodowania transportowego Base64.

Format dokumentu (XML)

	<?xml version="1.0" encoding="UTF-8"?>
	<recurringActivation>
		<serviceID>ServiceID</serviceID>
		<transaction>
			<orderID>OrderID</orderID>
			<remoteID>RemoteID</remoteID>
			<amount>999999.99</amount>
			<currency>PLN</currency>
			<gatewayID>GatewayID</gatewayID>
			<paymentDate>YYYYMMDDhhmmss</paymentDate>
			<paymentStatus>PaymentStatus</paymentStatus>                 
			<paymentStatusDetails>PaymentStatusDetails</paymentStatusDetails>
			<startAmount>999998.99</startAmount>
			<invoiceNumber>InvoiceNumber</invoiceNumber>
			<customerNumber>CustomerNumber</customerNumber>
			<customerEmail>CustomerEmail</customerEmail>
			<customerPhone>CustomerPhone</customerPhone>
		</transaction>
		<recurringData>
			<recurringAction>RecurringAction</recurringAction>
			<clientHash>ClientHash</clientHash>
			<expirationDate>YYYYMMDDhhmmss</expirationDate>
		</recurringData>
		<cardData>
			<index>Index</index>
			<validityYear>ValidityYear</validityYear>
			<validityMonth>ValidityMonth</validityMonth>
			<issuer>Issuer</issuer>
			<bin>BIN</bin>
			<mask>Mask</mask>
		</cardData>
		<hash>Hash</hash>
	</recurringActivation>

Wartości elementów: orderID, serviceID, amount dotyczące każdej z aktywowanych płatności automatycznych są identyczne z wartościami odpowiadających im pól podanymi przez Serwis przy rozpoczęciu danej płatności inicjalizacyjnej.

Opis zwracanych parametrów dla uruchomienia płatności automatycznej

WAŻNE! Kolejność atrybutów do wyliczenia Hash musi być zgodna z ich numeracją.

WSKAZÓWKA: Element hash (komunikatu) służy do autentykacji dokumentu. Wartość tego elementu obliczana jest jako wartość funkcji skrótu z łańcucha zawierającego sklejone wartości wszystkich pól dokumentu oraz dołączonego klucza współdzielonego. Opis sposobu obliczania skrótu znajduje się w części Bezpieczeństwo transakcji.

Odpowiedź na powiadomienie

W odpowiedzi na powiadomienie oczekiwany jest status HTTP 200 (OK) oraz tekst w formacie XML (nie kodowany Base64), zwracany przez Serwis Partnera w tej samej sesji HTTP, zawierający potwierdzenie otrzymania komunikatu.

Struktura potwierdzenia (XML)

	<?xml version="1.0" encoding="UTF-8"?>
	<confirmationList>
		<serviceID>ServiceID</serviceID>
		<recurringConfirmations>
			<recurringConfirmed>
				<clientHash>ClientHash</clientHash>
				<confirmation>Confirmation</confirmation>
			</recurringConfirmed>
		</recurringConfirmations>
		<hash>Hash</hash>
	</confirmationList>

Element confirmation płatności automatycznej

Element confirmation służy do przekazania stanu weryfikacji autentyczności transakcji przez Serwis Partnera. Wartość elementu wyznaczana jest przez sprawdzenie poprawności wartości parametru serviceID, porównanie wartości pól orderID i amount w komunikacie powiadomienia oraz w komunikacie rozpoczynającym transakcję, a także weryfikację zgodności wyliczonego skrótu z parametrów komunikatu z wartością przekazaną w polu hash komunikatu.

Przewidziano dwie wartości elementu confirmation:

a) CONFIRMED – wartości parametrów w obu komunikatach oraz parametr hash są zgodne – transakcja autentyczna;

b) NOTCONFIRMED – wartości w obu komunikatach są różne lub niezgodność hash – transakcja nieautentyczna;

WSKAZÓWKA: Element hash (w odpowiedzi na komunikat) służy do autentykacji odpowiedzi i liczony jest z wartości parametrów odpowiedzi. Opis sposobu obliczania skrótu znajduje się w części Bezpieczeństwo transakcji.

W wypadku braku poprawnej odpowiedzi na wysłane powiadomienia, System płatności online podejmie kolejne próby jego przekazania po upływie określonego czasu. Serwis Partnera powinien wykonywać własną logikę biznesową (np. uruchomienie usługi płatności automatycznej, mailingu itp.) jedynie po pierwszym komunikacie o danym ClientHash.

Schemat ponawiania komunikatów ITN/ISTN/IPN/RPAN/RPDN

Poniżej schemat opisujący planowe ponawianie komunikatów (zastrzegamy jednak możliwość ponowienia każdego z nich w dowolnym momencie).

UWAGA: Ciągłe ponawianie przez System identycznego komunikatu oznacza brak lub nieprawidłową na niego odpowiedź z Serwisu, oraz wymaga od Partnera pilnej diagnozy przyczyny.

Obciążenie dla płatności automatycznej

Poprawne odebranie identyfikatora usługi (ClientHash), sprawia, że Partner jest gotowy do automatycznego obciążania Klienta za towary/usługi zakupione w Serwisie. Proces składa się z transakcji oraz komunikacji ITN.

Poniżej proces automatycznego obciążenia Klienta za usługę/towar (a więc RecurringAction=MANUAL/AUTO i rozliczenie transakcji do Partnera).

Komunikat ITN wysyłany po płatności automatycznej jest podobny do tych, otrzymywanych po płatnościach jednorazowych. Rozszerzony jest jedynie o węzeł RecurringData oraz (dla płatności kartowej) CardData.

Komunikat startu transakcji płatności automatycznej

Aby wykonać automatyczne obciążenie, Serwis Partnera powinien wykonać Przedtransakcję z parametrem ClientHash, zgodnym z aktywowaną wcześniej usługą płatności automatycznej (pochodzące z RPAN), z parametrem RecurringAcceptanceState o wartości NOT_APPLICABLE oraz odpowiednią wartość parametru RecurringAction:

a) AUTO - płatność cykliczna (obciążenie bez udziału Klienta),

b) MANUAL - płatność jednym kliknięciem (obciążenie zlecane przez Klienta, zwane OneClick).

UWAGA: Udział klienta w opcji MANUAL, zazwyczaj ogranicza się do wywołania komunikatu (wybranie w Serwisie opcji zapłaty zapamiętaną kartą). W zdecydowanej większości przypadków wymagana jest dodatkowa autoryzacja w banku (w postaci 3DS lub kodu CVC). Wtedy zamiast obciążenia (i statusu zlecenia w odpowiedzi na przedtranksację), System zwróci link do kontynuacji – takie jest domyślne zachowanie systemu na środowisku testowym. Aby przetestować scenariusz obciążenia bez potrzeby dodatkowej autoryzacji należy zgłosić potrzebę zmiany konfiguracji Systemu na czas testu.

UWAGA: Opcja niedostępna dla płatności automatycznych BLIK (BLIK OneClick).

Dezaktywacja usługi

Partner może dezaktywować usługę płatności automatycznych w dowolnym momencie. Proces może składać się z komunikatu zlecającego dezaktywację oraz komunikatu RPDN (dedykowanego dla zdarzeń rezygnacji z usługi płatności automatycznej).

Może się również zdarzyć, że rezygnacja z usługi zostanie zainicjowana ze strony AP (np. na wniosek Klienta, banku lub organizacji kartowej). W takiej sytuacji System również dostarczy komunikat RPDN.

Komunikat dezaktywacji płatności automatycznej

Serwis może wyłączyć usługę poprzez dedykowany komunikat. Wszystkie parametry przekazywane są metodą POST (na adres https://{host_bramki}/deactivate_recurring). Protokół rozróżnia wielkość liter zarówno w nazwach jak i wartościach parametrów. Wartości przekazywanych parametrów powinny być kodowane w UTF-8.

Lista parametrów dezaktywacji płatności automatycznej

WAŻNE! Kolejność atrybutów do wyliczenia Hash musi być zgodna z ich numeracją.

UWAGA: Element Hash (komunikatu) służy do autentykacji dokumentu. Wartość tego elementu obliczana jest jako wartość funkcji skrótu z łańcucha zawierającego sklejone wartości wszystkich pól dokumentu oraz dołączonego klucza współdzielonego.

Odpowiedź

W odpowiedzi na powiadomienie zwracany jest tekst w formacie XML w tej samej sesji HTTP, zawierający potwierdzenie.

Struktura potwierdzenia (XML)

	<?xml version="1.0" encoding="UTF-8"?>
	<confirmationList>
		<serviceID>ServiceID</serviceID>
		<messageID>MessageID</messageID>
		<recurringConfirmations>
			<recurringConfirmed>
				<clientHash>ClientHash</clientHash>
				<confirmation>Confirmation</confirmation>
				<reason>Reason</reason>
			</recurringConfirmed>
		</recurringConfirmations>
		<hash>Hash</hash>
	</confirmationList>

Element confirmation

Element confirmation służy do przekazania stanu weryfikacji autentyczności operacji przez Serwis. Wartość elementu wyznaczana jest przez sprawdzenie poprawności wartości parametrów serviceID oraz clientHash z podanymi w komunikacie RPAN przy rozpoczęciu danej płatności aktywacyjnej, a także weryfikację zgodności wyliczonego skrótu z parametrów komunikatu z wartością przekazaną w polu Hash.

Przewidziano dwie wartości elementu confirmation:

a) CONFIRMED – wartości parametrów są poprawne oraz parametr Hash są zgodne – operacja autentyczna;

b) NOTCONFIRMED – wartości w obu komunikatach są niepoprawne lub niezgodność Hash – operacja nieautentyczna;

UWAGA: Element hash (w odpowiedzi na komunikat) służy do autentykacji odpowiedzi i liczony jest z wartości parametrów odpowiedzi. Wartość tego elementu obliczana jest jako wartość funkcji skrótu z łańcucha zawierającego sklejone wartości wszystkich pól dokumentu (bez znaczników) oraz dołączonego klucza współdzielonego. Opis w części Bezpieczeństwo transakcji.

Powiadomienie o dezaktywacji płatności automatycznej (RPDN)

Po wyłączeniu płatności automatycznej dla danego ClientHash, wysyłany jest dedykowany komunikat w postaci dokumentu XML, jest protokołem HTTPS (domyślnie port 443), metodą POST, z parametrem o nazwie recurring. Parametr ten zapisany jest mechanizmem kodowania transportowego Base64.

Format dokumentu (XML)

	<?xml version="1.0" encoding="UTF-8"?>
	<recurringDeactivation>
		<serviceID>ServiceID</serviceID>
		<recurringData>
			<recurringAction>RecurringAction</recurringAction>
			<clientHash>ClientHash</clientHash>
			<deactivationSource>DeactivationSource</deactivationSource>
			<deactivationDate>DeactivationDate</deactivationDate>
		<recurringData>
		<hash>Hash</hash>
	</recurringDeactivation>

Wartości elementów: serviceID, clientHash dotyczące każdej z deaktywowanych płatności cyklicznych, są identyczne z wartościami odpowiadających im pól, podanymi w komunikacie RPAN przy rozpoczęciu danej płatności inicjalizacyjnej.

Opis zwracanych parametrów

WAŻNE! Kolejność atrybutów do wyliczenia Hash musi być zgodna z ich numeracją.

UWAGA: Element hash (komunikatu) służy do autentykacji dokumentu. Wartość tego elementu obliczana jest jako wartość funkcji skrótu z łańcucha zawierającego sklejone wartości wszystkich pól dokumentu oraz dołączonego klucza współdzielonego.

Potwierdzenie otrzymania komunikatu

W odpowiedzi na powiadomienie oczekiwany jest status HTTP 200 (OKq) oraz tekst w formacie XML (nie kodowany Base64), zwracany przez Serwis w tej samej sesji HTTP, zawierający potwierdzenie otrzymania komunikatu.

Struktura potwierdzenia (XML)

	<?xml version="1.0" encoding="UTF-8"?>
	<confirmationList>
		<serviceID>ServiceID</serviceID>
		<recurringConfirmations>
			<recurringConfirmed>
				<clientHash>ClientHash</clientHash>
				<confirmation>Confirmation</confirmation>
			</recurringConfirmed>
		</recurringConfirmations>
		<hash>Hash</hash>
	</confirmationList>

Element Confirmation

Element confirmation służy do przekazania stanu weryfikacji autentyczności operacji przez Serwis. Wartość elementu wyznaczana jest przez sprawdzenie poprawności wartości parametrów serviceID oraz clientHash z podanymi w komunikacie RPAN przy rozpoczęciu danej płatności inicjalizacyjnej oraz weryfikację zgodności wyliczonego skrótu z parametrów komunikatu z wartością przekazaną w polu hash.

Przewidziano dwie wartości elementu confirmation:

a) CONFIRMED – wartości parametrów są poprawne oraz parametr hash są zgodne – operacja autentyczna

b) NOTCONFIRMED – wartości w obu komunikatach są niepoprawne lub niezgodność hash – operacja nieautentyczna

UWAGA: Element hash (w odpowiedzi na komunikat) służy do autentykacji odpowiedzi i liczony jest z wartości parametrów odpowiedzi. Wartość tego elementu obliczana jest jako wartość funkcji skrótu z łańcucha zawierającego sklejone wartości wszystkich pól dokumentu (bez znaczników) oraz dołączonego klucza współdzielonego. Opis sposobu obliczania skrótu znajduje się w części Bezpieczeństwo transakcji.

W wypadku braku poprawnej odpowiedzi na wysłane powiadomienia, System podejmie kolejne próby jego przekazania po upływie określonego czasu. Serwis powinien wykonywać własną logikę biznesową (np. zatrzymanie płatności automatycznej, mailing itp.), jedynie po pierwszym komunikacie RPDN o danym ClientHash.

WSKAZÓWKA: Zalecamy zapoznanie się również z częściami Monitoring komunikacji ITN/ISTN/IPN/RPAN/RPDN i Schemat ponawiania komunikatów ITN/ISTN/IPN/RPAN/RPDN.

Weryfikacja tożsamości płatnika

Opis weryfikacji tożsamości płatnika

Dokonanie weryfikacji tożsamości płatnika może dobywać się na zasadzie porównania danych przekazanych do weryfikacji w parametrach startu transakcji oraz danych uzyskanych z wpłaty zarejestrowanej w Systemie. Jeśli w trakcie integracji zostanie uzgodniona opcja weryfikacji danych oraz w starcie transakcji zostaną podane zadeklarowane przez klienta dane do weryfikacji, System dokona sprawdzenia prawdziwości tych danych i jego wynik umieści w komunikacie ITN obok danych nadawcy przelewu. Dla większości transakcji typu PBL, pierwszy komunikat ITN nie będzie zawierać danych adresowych (nazw, adres) klienta. Dane te są uzupełniane w Systemie po zeskanowaniu historii rachunku AP danego kanału płatności. Uzupełnienie tych danych skutkuje wysłaniem kolejnego komunikatu ITN do Partnera, zawierającego już te dane.

Pola w komunikacie startu transakcji powiązane z usługą (opis w części Rozpoczęcie transakcji z dodatkowymi parametrami):

• VerificationFName,

• VerificationLName,

• VerificationStreet,

• VerificationStreetHouseNo,

• VerificationStreetStaircaseNo,

• VerificationStreetPremiseNo,

• VerificationPostalCode,

• VerificationCity,

• VerificationNRB

Pola w komunikacie ITN powiązane z usługą (opisane w części Dodatkowe pola w komunikacie ITN/IPN transakcji wejściowej):

• węzeł customerData

• verificationStatus

• węzeł verificationStatusReasons

WSKAZÓWKA: Szczegółowe instrukcje, jak interpretować statusy płatności i weryfikacji w tym procesie zawiera część Dodatkowe pola w komunikacie ITN/IPN transakcji wejściowej.

Rozpoczęcie transakcji z dodatkowymi parametrami

Starty transakcji mogą zostać przeprowadzone z dodatkowymi parametrami rozpisanymi w poniższych punktach.

WAŻNE! Kolejność atrybutów do wyliczenia Hash musi być zgodna z ich numeracją.

Koszyk produktów

Opis koszyka produktów

Koszyk produktów przesyłany jest jako parametr (metody POST) o nazwie Products. Jego wartość jest zakodowana protokołem transportowym Base64.

Format przed zakodowaniem (XML)

	<?xml version="1.0" encoding="UTF-8"?>
	<productList>
		<product>
			<subAmount>SubAmount1</subAmount>
			<params>Params1</params>
		</product>
		<product>
			<subAmount>SubAmount2</subAmount>
			<params>Params2</params>
		</product>
		…
		<product>
			<subAmount>SubAmountN</subAmount>
			<params>ParamsN</params>
		</product>
	</productList>

Węzeł productList musi zawierać przynajmniej 1 element product, każdy węzeł product musi zawierać po jednym elemencie subAmount i params.

Element subAmount musi zawierać dodatnią kwotę produktu (separatorem dziesiętnym jest kropka, a po niej występują dwie cyfry groszy). Suma kwot kolejnych produktów musi być równa kwocie podanej w parametrze Amount (kwocie transakcji).

W przypadku niespełnienia powyższych warunków System zwróci błąd.

Element Params

Element params może służyć do przekazywania informacji charakterystycznych dla danego produktu. Nazwy parametrów oraz ich znaczenie podlega każdorazowo uzgodnieniom w formie roboczej podczas integracji.

Przykładowe parametry produktu i ich znaczenie poniżej.

• W tym wypadku węzeł zawiera nazwę produktu:

		<params>
			<param name="productName" value="Nazwa produktu 1" />
		</params>

• W tym wypadku węzeł zawiera dwie wartości przypisane do danego produktu, mogące oznaczać przykładowo typ produktu oraz jego nazwę:

		<params>
			<param name="productType" value="ABCD" />
			<param name="productName" value="Nazwa produktu 1" />
		</params>

• W przypadku, gdy Serwis posiada saldo w Systemie, oraz planuje wykonywać zwroty do Klienta całości, bądź części kwoty wpłaconej na rzecz wskazanego produktu, zobowiązany jest przekazywać w produkcie jego unikalny identyfikator (parametr o nazwie productID o typie string{1,36} (Dopuszczalne alfanumeryczne znaki alfabetu łacińskiego oraz znaki: _ i -)):

		<params>
			<param name="productID" value="12456" />
		</params>

• W przypadku, gdy Partner korzysta z rozszerzonej struktury (wiele punktów rozliczeń), zobowiązany jest przekazywać w każdym produkcie identyfikator punktu rozliczeń (parametr o nazwie idBalancePoint o typie integer{1,10}):

		<params>
			<param name="idBalancePoint" value="12456" />
		</params>

• W przypadku, gdy Partner korzysta z rozliczeń MASS_TRANSFER, tj:

  • każda transakcja rozliczana jest bezpośrednio po wpłacie oraz

  • rozliczenia wykonują się na poziomie produktu/punktu rozliczeń (czyli po wpłacie wykonywane jest tyle przelewów rozliczeniowych, co produktów w koszyku), oraz

  • nie ustalono stałych danych do rozliczeń (lub nie wszystkie dane do rozliczeń są ustalone na sztywno w konfiguracji rozliczeń),

Partner musi przekazać w każdym produkcie brakujące dane do rozliczeń tego produktu. Dostępne parametry stanowiące dane to:

• customerNRB – docelowy numer rachunku do rozliczeń.
  Format NRB (26 cyfr z sumą kontrolną). Jeśli w trakcie integracji ustalono wykorzystanie rachunków spoza Polski, wtedy pole przenosi IBAN i oczekiwany zakres danych pola zmienia się na: alfanumeryczne znaki alfabetu łacińskiego (min. 15, max. 32 znaki). Podanie wartości w formacie IBAN spowoduje potrzebę podania w produkcie również parametrów swiftCode, foreignTransferMode.

• title - tytuł przelewu rozliczającego produkt. W niektórych przypadkach, niezależnych od AP, tytuł przelewu rozliczeniowego może zostać samodzielnie zmodyfikowany przez Bank, z którego nastąpiło rozliczenie.
  Dopuszczalne alfanumeryczne znaki alfabetu łacińskiego oraz znaki z zakresu: ĘęÓ󥹌śŁłŻżŹźĆćŃń\s.-,!()"

• receiverName - nazwa odbiorcy przelewu rozliczającego produkt.
  Dopuszczalne alfanumeryczne znaki alfabetu łacińskiego oraz znaki z zakresu: ĘęÓ󥹌śŁłŻżŹźĆćŃń\s.-/,!()=[]{};:?

Przykład zastosowania parametrów w produkcie:

	<params>
		<param name="customerNRB" value="83109010980000000107285707" />
		<param name="title" value="Rozliczenie produktu X" />
		<param name="receiverName" value="Jan Kowalski" />
	</params>

• W modelu Marketplace, Partner zobowiązany jest przekazywać w każdym produkcie identyfikator punktu rozliczeń (parametr o nazwie idBalancePoint o typie integer{1,10}). Dotyczy to również zasileń salda punktu rozliczeń.

Przykładowe parametry koszyka:

	<params>
		<param name="idBalancePoint" value="12456" />
		<param name="productName" value="Zasilenie salda dla Autopay" />
	</params>

Wyświetlanie koszyka produktów na ekranie wyboru Kanału Płatności

Jeżeli w trakcie rozmów dotyczących koszyka produktów ustalono, że jego podsumowanie ma zostać wyświetlone na stronie Systemu (ekran wyboru Kanału Płatności), można określić etykiety każdego użytego w koszyku parametru. System może użyć domyślnej etykiety parametru lub może przyjąć ją w starcie transakcji.

Wartość atrybutu title zostanie wyświetlona przed wartością parametru produktu.

Przykład atrybutu title

	<params>
		<param name="productName" value="Nazwa produktu 1" title="Nazwa"/>
		<param name="productType" value="ABCD" title="Typ"/>
	</params>

Dodatkowe opcje komunikacji online do Partnera

Dodatkowe pola w komunikacie ITN/IPN transakcji wejściowej

Opis

Natychmiastowe powiadomienia o zmianie statusu transakcji mogą zawierać dodatkowe pola (patrz Schematy dla Preautoryzacji). Ich występowanie jest kwestią konfiguracyjną, ustalaną w trakcie integracji (domyślnie wysyłane jest tylko węzeł customerData).

O tym, czy jest to komunikat ITN, czy IPN decyduje jedynie występowanie węzła product.

Pełna lista dodatkowych pól w komunikacie ITN/IPN

WAŻNE! Kolejność atrybutów do wyliczenia Hash musi być zgodna z ich numeracją.

UWAGA: Do liczenia wartości Hash pobierane są atrybuty value kolejnych węzłów product.params.

Przykład komunikatu ITN/IPN z dodatkowymi parametrami (XML)

	<?xml version="1.0" encoding="UTF-8"?>
	<transactionList>
	  <serviceID>ServiceID</serviceID>
	  <transactions>
	  <transaction>
		<orderID>OrderID</orderID>
		<remoteID>RemoteID</remoteID>
		<amount>999999.99</amount>
		<currency>PLN</currency>
		<gatewayID>GatewayID</gatewayID>
		<paymentDate>YYYYMMDDhhmmss</paymentDate>
		<paymentStatus>PaymentStatus</paymentStatus>                 
		<paymentStatusDetails>PaymentStatusDetails</paymentStatusDetails>
		<addressIP>127.0.0.1</addressIP>
		<customerNumber>1111111</customerNumber>
		<title>title</title>
		<customerData>
		  <fName>fName</fName>
		  <lName>lName</lName>
		  <streetName>streetName</streetName>
		  <streetHouseNo>streetHouseNo</streetHouseNo>
		  <streetStaircaseNo>streetStaircaseNo</streetStaircaseNo>
		  <streetPremiseNo>streetPremiseNo</streetPremiseNo>
		  <postalCode>postalCode</postalCode>
		  <city>city</city>
		  <nrb>nrb</nrb>
		  <senderData>senderData</senderData>    
		</customerData>
		<verificationStatus>verificationStatus</verificationStatus>
		<verificationStatusReasons>
		   <verificationStatusReason>reason1</verificationStatusReason>
		   <verificationStatusReason>reason2</verificationStatusReason>
		   <verificationStatusReason>reason3</verificationStatusReason>
		</verificationStatusReasons>
		<startAmount>999998.99</startAmount>    
		<recurringData>
			<recurringAction>RecurringAction</recurringAction>
			<clientHash>ClientHash</clientHash>
			<expirationDate>YYYYMMDDhhmmss</expirationDate>
		</recurringData>
		<cardData>
			<index>Index</index>
			<validityYear>ValidityYear</validityYear>
			<validityMonth>ValidityMonth</validityMonth>
			<issuer>Issuer</issuer>
			<bin>BIN</bin>
		</cardData>
		<product>
			<subAmount>SubAmount</subAmount>
			<params>
				<param name="idBalancePoint" value="idBalancePoint"/>
				<param name="invoiceNumber" value="invoiceNumber"/>
				<param name="customerNumber" value="customerNumber"/>
				<param name="subAmount" value="SubAmount"/>
			</params>
		</product>
	  </transaction>
	  </transactions>
	  <hash>Hash</hash>
	</transactionList>

Szczegółowy opis zmiany statusu weryfikacji – dla transakcji zakończonej poprawnie (wynik pozytywny lub negatywny)

Szczegółowy opis zmiany statusu weryfikacji – dla transakcji nie zakończonej poprawnie

Szczegółowe statusy transakcji

Komunikat ITN dla transakcji wejściowej zawiera oprócz statusu płatności (pole paymentStatus) szczegółowy opis tego statusu (pole paymentStatusDetails). Opis ten należy traktować informacyjnie, lista jego dozwolonych wartości jest ciągle powiększana i pojawienie się nowych wartości nie może pociągać za sobą brak akceptacji komunikatu ITN.

Wartości statusów transakcji – Statusy ogólne (niezależne od kanału płatności)

Wartości statusów transakcji – Statusy kartowe

Wartości statusów transakcji – Statusy specyficzne dla transakcji BLIK

Natychmiastowe powiadomienia o zmianie statusu produktu (IPN)

W przypadku Partnera korzystającego z rozszerzonej struktury (Koszyka produktów z wieloma punktami rozliczeń), System udostępnia niezależne powiadamianie o zmianach statusów każdego z produktów. Taka usługa ma sens, jeśli poszczególne punkty rozliczeń powinny otrzymywać własne powiadomienia. W tym przypadku konfiguracja IPN (adres do powiadomień, umieszczane w komunikacie pola itp.) przechowywana jest właśnie na poziomie konfiguracji punktu rozliczeń. Struktura IPN jest podobna do ITN (rozszerzona jedynie o węzeł product podobny do opisanego w w rozdziale Dodatkowe pola w komunikacie ITN/IPN transakcji wejściowej, uzupełniony jedynie o powtórzenie kwoty subAmount w params). Przykład IPN w podrozdziale Dodatkowe pola w komunikacie ITN/IPN transakcji wejściowej).

Natychmiastowe powiadomienia o zmianie statusu transakcji rozliczeniowej (ISTN)

Istnieje możliwość dostarczania komunikatów o wszystkich wypłatach (rozliczeniach, wypłatach z salda i zwrotach) wykonywanych przez System w ramach usługi płatności. Ponieważ usługa nie jest domyślnie uruchomiona, zapotrzebowanie na nią, wraz z adresem do wysyłki ISTN, musi być przez Partnera zgłoszone w trakcie ustalania wymagań.

W przypadku skutecznego uruchomienia komunikacji ISTN, System niezwłocznie przekazuje powiadomienia o fakcie zlecenia transakcji rozliczeniowej (ew. wypłatach/zwrotach) oraz zmianie jej statusu. Potwierdzenia przesyłane są, na ustalony w trakcie dodawania konfiguracji Serwisu Partnera, adres na serwerze Serwisu Partnera:

https://sklep_nazwa/odbior_informacji_o_rozliczeniu

Powiadomienie to polega na wysłaniu przez System dokumentu XML zawierającego nowe statusy transakcji. Dokument wysyłany jest protokołem HTTPS (domyślnie port 443). Dokument przesyłany jest metodą POST, jako parametr HTTP o nazwie transactions. Parametr ten zapisany jest mechanizmem kodowania transportowego Base64.

Format dokumentu (XML)

	<?xml version="1.0" encoding="UTF-8"?>
	<transactionList>
		<serviceID>ServiceID</serviceID>
		<transactions>
			<transaction>
				<isRefund>true/false</isRefund>
				<productID>ProductID</productID>
				<orderID>OrderID</orderID>
				<orderOutID>OrderOutID</orderOutID>
				<remoteID>RemoteID</remoteID>
				<remoteOutID>RemoteOutID</remoteOutID>
				<amount>999999.99</amount>
				<currency>PLN</currency>
				<transferDate>YYYYMMDDhhmmss</transferDate>
				<transferStatus>TransferStatus</transferStatus>                 
				<transferStatusDetails>TranasferStatusDetails</transferStatusDetails>
				<title>Title</title>
				<receiverBank>ReceiverBank</receiverBank>      
				<receiverNRB>ReceiverNRB</receiverNRB>
				<receiverName>ReceiverName</receiverName>
				<receiverAddress>ReceiverAddress</receiverAddress>
				<senderBank>SenderBank</senderBank>
				<senderNRB>SenderNRB</senderNRB>
			</transaction>
		</transactions>
		<hash>Hash</hash>
	</transactionList>

Zwracane parametry

WAŻNE! Kolejność atrybutów do wyliczenia Hash musi być zgodna z ich numeracją.

Odpowiedź na powiadomienie

W odpowiedzi na powiadomienie oczekiwany jest tekst w formacie XML (nie kodowany Base64), zwracany przez Serwis Partnera w tej samej sesji HTTP, zawierający potwierdzenie otrzymania statusu transakcji.

Struktura potwierdzenia (XML)

	<?xml version="1.0" encoding="UTF-8"?>
	<confirmationList>
		<serviceID>ServiceID</serviceID>
		<transactionsConfirmations>
			<transactionConfirmed>
				<remoteOutID>RemoteOutID</remoteOutID>
				<confirmation>Confirmation</confirmation>
			</transactionConfirmed>
		</transactionsConfirmations>
		<hash>Hash</hash>
	</confirmationList>

Element confirmation służy do przekazania stanu weryfikacji autentyczności transakcji przez Serwis Partnera. Wartość elementu wyznaczana jest przez sprawdzenie poprawności wartości parametru serviceID, a także weryfikację zgodności wyliczonego skrótu z wartością przekazaną w polu hash.

Przewidziano dwie wartości tego elementu:

a) CONFIRMED – parametr hash jest zgodny – transakcja autentyczna;

b) NOTCONFIRMED – parametr hash jest niezgodny– transakcja nieautentyczna;

W wypadku braku poprawnej odpowiedzi na wysłane powiadomienia, System podejmie kolejne próby przekazania nowego statusu po upływie określonego czasu. Serwis Partnera powinien wykonywać własną logikę biznesową, jedynie po pierwszym komunikacie o danym statusie płatności.

WSKAZÓWKA: Warto zapoznać się ze Schematem ponawiania komunikatów ITN/ISTN/IPN/RPAN/RPDN.

Szczegółowy opis zachowania i zmiany statusów rozliczenia (transferStatus)

W podstawowym modelu, System dostarczy jedynie status SUCCESS, możliwe jest jednak dokładniejsze powiadamianie. Opcja pełna powinna być zgłoszona podczas integracji i wiąże się z poniższym schematem przejść statusów.

Zlecenie transakcji rozliczeniowej powoduje wysłanie statusu PENDING. Później system dostarczy SUCCESS lub FAILURE. Dla transakcji, dla której wystąpił status SUCCESS, nie powinna już nastąpić zmiana statusu na FAILURE. Może jednakże nastąpić zmiana statusu szczegółowego (kolejne komunikaty o zmianie statusu szczegółowego są jedynie informacyjne i nie powinny pociągać za sobą ponownego wykonywania żadnej logiki biznesowej).

W szczególnych przypadkach (np. błąd w banku) transakcja pierwotnie potwierdzona, może zostać przekazana do ponownego wykonania, a więc zmienić swój status na PENDING i ponownie na SUCCESS.

Innym szczególnym przypadkiem może być status FAILURE (np. po błędzie wewnętrznym Systemu), następnie zastąpiony statusem SUCCESS.

Usługi dodatkowe

Odpytywanie o listę aktualnie dostępnych Kanałów Płatności

Opis

Aby zbudować w Serwisie widok wyboru metody płatności, System umożliwia zdalne odpytanie o aktualną listę kanałów płatności. W tym celu należy wywołać metodę gatewayList (https://host_bramki/gatewayList/v2) z odpowiednimi parametrami (w formacie JSON). Wszystkie parametry przekazywane są za pomocą technologii REST. Protokół rozróżnia wielkość liter zarówno w nazwach jak i wartościach parametrów. Wartości przekazywanych parametrów powinny być kodowane w UTF-8.

Lista dostępnych parametrów

WAŻNE! Kolejność atrybutów do wyliczenia Hash musi być zgodna z ich numeracją.

Przykładowy komunikat

	{
		"ServiceID": 47498,
		"MessageID": "11111111111111111111111111111111",
		"Hash":"aeaa52d56d9f0f4906e9affc7719911584c0eaef2c88178ffd1e20771db0fe07",
		"Currencies":"PLN,EUR"
	}

Odpowiedź na żądanie

W odpowiedzi na żądanie zwracana jest (w tej samej sesji HTTP) lista, zawierająca kolejne Kanały płatności (gatewayID), ich nazwę, typ, opis, adres logotypu oraz informację o stanie oraz aktualności statusu (będzie on odświeżany co kilka minut).

Poniżej opis tych pól:

WAŻNE! Kolejność atrybutów do wyliczenia Hash musi być zgodna z ich numeracją.

Przykładowa odpowiedź

	{
		"result": "OK",
		"errorStatus": null,
		"description": null,
		"serviceID": "47498",
		"messageID": "11111111111111111111111111111111",
		"gatewayList": [
			{
				"gatewayID": 1500,
				"gatewayName": "PBC płatność testowa",
				"gatewayType": "PBL",
				"bankName": "NONE",
				"iconURL": "https://{host_bramki}/pomoc/grafika/1500.gif",
				"state": "OK",
				"stateDate": "2020-08-17 16:45:05",
				"gatewayDescription": null,
				"inBalanceAllowed": false,
				"minValidityTime": 5,
				"currencyList": [
					{
							"currency": PLN,
							"minAmount": 1.00,
							"maxAmount": 30000.00
					}
				]
			},
			{
				"gatewayID": 1800,
				"gatewayName": "mBank PSD2",
				"gatewayType": "PBL",
				"bankName": "NONE",
				"iconURL": "https://{host_bramki}/pomoc/grafika/3.gif",
				"state": "OK",
				"stateDate": "2020-08-17 16:45:05",
				"gatewayDescription": null,
				"inBalanceAllowed": true,
				"currencyList": [
					{
							"currency": PLN,
							"minAmount": 0.01
					},
					{
							"currency": EUR
					}
				]
			}
		],
		"hash": "d3ffb125bd1effeb27f46af7fcbada36fb1b9df0ff81438db98ecd06f502c8b9",
	}

UWAGA: Wynik odpytania metody powinno się co odświeżać 1-2h (zbyt częste wołanie gatewayList zwiększy obciążenie obu systemów, nie wnosząc wiele korzyści). W przypadku braku lub nieprawidłowej odpowiedzi, należy wyświetlić ostatnią znaną i poprawną konfigurację Kanałów Płatności. Jest to drugi powód do przechowywania tymczasowej kopii gatewayList w Serwisie Partnera. Jako nieprawidłową odpowiedź należy traktować pustą odpowiedź, timeout, nieprawidłowy Hash, bądź pustą listę węzłów gateway.

Odpytywanie o listę aktualnie dostępnych zgód formalnych

Opis

Opis integracji umożliwiający używanie listy płatności osadzonej w serwisie (lub aplikacji mobilnej), bez kroków przejściowych. W niektórych przypadkach zamiast kroku przejściowego, standardowe zachowanie systemu przewiduje blokadę startu transakcji.

Należy wyświetlić odpowiednie treści formalne (a więc klauzule informacyjne oraz ew. regulaminy) już w momencie wyboru formy płatności, a następnie przekazać do Systemu Płatności Online potwierdzenie ich wyświetlenia oraz ew. akceptacji (w postaci identyfikatorów).

System umożliwia zdalne odpytanie o aktualną listę obowiązków i powiązanych treści formalnych. W tym celu należy wywołać metodę legalData (https://host_bramki/legalData) z odpowiednimi parametrami (w formacie JSON).

WSKAZÓWKA: Wszystkie parametry przekazywane są za pomocą technologii REST. Protokół rozróżnia wielkość liter zarówno w nazwach jak i wartościach parametrów. Wartości przekazywanych parametrów powinny być kodowane w UTF-8.

Lista dostępnych parametrów

WAŻNE! Kolejność atrybutów do wyliczenia Hash musi być zgodna z ich numeracją.

Przykładowy komunikat

	{
		"ServiceID": 102422,
		"MessageID": "11111111111111111111111111111111",
		"GatewayID": 1500,
		"Language": "PL",
		"Hash":"61789013d932e2bc728d6206f7e9222b93e3176f7f07f6aa8cce1ccd65afaf0d"
	}

Lista zwracanych parametrów

W odpowiedzi na żądanie zwracana jest (w tej samej sesji HTTP) lista, zawierająca kolejne treści formalne w postaci: ID, typ i brzmienie treści, ich umiejscowienie w Serwisie, adres do regulaminu oraz inne informacje dodatkowe.

WAŻNE! Kolejność atrybutów do wyliczenia Hash musi być zgodna z ich numeracją.

Przykładowa odpowiedź

	{
		"serviceID": "102422",
		"messageID": "11111111111111111111111111111111",
		"gatewayID": "1500",
		"language": "PL",
		"serviceModel": "PAYER",
		"regulationList": [
			{
				"regulationID": 6288,
				"type": "RECURRING",
				"url": "https://host/path?params",
				"labelList": [
					{
						"labelID": 1,
						"inputLabel": "<ul><li>\r\nZapoznałem się i akceptuję <a id=\"regulations_pdf\" target=\"_blank\" href=https://{host_bramki}/path?params>Regulamin świadczenia usług płatniczych</a> oraz <a class=\"privacy-policy\" href=\"https://{host_bramki}/polityka-prywatnosci.pdf\" target=\"_blank\">Politykę prywatności</a></li><li>\r\nChcę aby usługa została zrealizowana niezwłocznie, a w przypadku odstąpienia od umowy, wiem, że nie otrzymam zwrotu poniesionych kosztów za usługi zrealizowane na moje żądanie do chwili odstąpienia od umowy\r\n</li></ul>",
						"placement": "ABOVE_BUTTON",
						"showCheckbox": true,
						"checkboxRequired": true
					}
				]
			},
			{
				"regulationID": 1,
				"type": "PRIVACY",
				"labelList": [
					{
						"labelID": 1,
						"inputLabel": "Autopay korzysta z plików cookie. Pozostając na tej stronie, wyrażasz zgodę na korzystanie z plików cookie zgodnie z <a class=\"privacy-policy\" href="?r="https://{host_bramki}/polityka-prywatnosci.pdf\" target=\"_blank\">Polityką prywatności Autopay S.A. </a> Możesz samodzielnie zarządzać cookies zmieniając odpowiednio ustawienia swojej przeglądarki lub oprogramowania urządzenia."
						"placement": "BOTTOM_OF_PAGE",
						"showCheckbox": false,
						"checkboxRequired": false
					}
				]
			}
		],
		"hash": "61789013d932e2bc728d6206f7e9222b93e3176f7f07f6aa8cce1ccd65afaf0d",
		"result": "OK",
		"errorStatus": null,
		"description": null
	}

Opis obsługi odpowiedzi

Ponieważ wymogi formalne dotyczące treści klauzul, ich rozmieszczenie oraz sposób akceptacji zależą od stosowanego kanału płatniczego, metoda ta powinna być wywoływana każdorazowo po jego wyborze (stąd obowiązkowy parametr GatewayID).

Odpowiednie treści i zachowanie powinny być dynamicznie dostosowywane do odpowiedzi z Systemu (np. powinien pojawić się wymagany checkbox z klauzulą informacyjną oraz linkiem do regulaminu). Oczywiście, aby aplikacja działała szybko, mile widziane jest używanie cache do zapamiętywania odpowiedzi niedawno wykonanych wywołań (np. na 15 minut).

Wyświetlona (i ew. zatwierdzona) w momencie przejścia do płatności zgoda, powinna być potwierdzona w Systemie poprzez dołączenie do komunikatu startu transakcji w parametrze startowym jej identyfikatora (a więc odpowiednią wartość regulationID).

W zależności od wartości pola type regulaminu:

- dla wyświetlanej/akceptowanej klauzuli o type=DEFAULT:

a. do parametru DefaultRegulationAcceptanceID powinna trafiać jej wartość regulationID;

b. do parametru DefaultRegulationAcceptanceState powinna trafić wartość ACCEPTED oraz

c. do parametru DefaultRegulationAcceptanceTime powinna trafić wartość odpowiadająca chwili akceptacji zgody poprzez zaznaczenie checkboxa oraz kliknięcie przycisku „Rozpocznij płatność"

- dla wyświetlanej/akceptowanej klauzuli o type=RECURRING:

a. do parametru RecurringAcceptanceID powinna trafiać jej wartość regulationID;

b. do parametru RecurringAcceptanceState powinna trafić wartość ACCEPTED oraz

c. do parametru RecurringAcceptanceTime powinna trafić wartość odpowiadająca chwili akceptacji zgody poprzez zaznaczenie checkboxa oraz kliknięcie przycisku „Rozpocznij płatność"

UWAGA: Pola (np. serviceModel, url, labelID) i wartości pól (np. PSD2, RODO, PRIVACY) metody legalData nie są wymagane do obsługi, ale należy przewidzieć możliwość ich występowania w odpowiedzi na żądanie.

Odpytanie o stan salda

Opis

Dla wszystkich serwisów możliwe jest odpytanie o aktualny stan salda. W tym celu należy wywołać metodę balanceGet https://{host_bramki}/webapi/balanceGet z odpowiednimi parametrami. Wszystkie parametry przekazywane są metodą POST (Content-Type: application/x-www-form-urlencoded). Protokół rozróżnia wielkość liter zarówno w nazwach jak i wartościach parametrów. Wartości przekazywanych parametrów powinny być kodowane w UTF-8.

Lista dostępnych parametrów dla aktualnego stanu salda

WAŻNE! Kolejność atrybutów do wyliczenia Hash musi być zgodna z ich numeracją.

Odpowiedź na żądanie aktualnego salda

W odpowiedzi na żądanie zwracany jest (w tej samej sesji HTTP) tekst w formacie XML, zawierający potwierdzenie przyjęcia operacji do realizacji lub opis błędu.

Struktura potwierdzenia (XML)

	<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
	<balanceGet>
		<serviceID>ServiceID</serviceID>
		<messageID>MessageID</messageID>
		<balance>Balance</balance>
		<currency>Currency</currency>
		<hash>Hash</hash>
	</balanceGet>

lub

	<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
	<balanceGet>
		<balancePointID>BalancePointID</balancePointID>
		<messageID>MessageID</messageID>
		<balance>Balance</balance>
		<currency>Currency</currency>
		<hash>Hash</hash>
	</balanceGet>

Lista pól odpowiedzi

WAŻNE! Kolejność atrybutów do wyliczenia Hash musi być zgodna z ich numeracją.

Zasilanie salda

Opis

Dla serwisów posiadających saldo w Systemie, możliwe jest wykonanie operacji zasilenia salda na poczet przyszłych zwrotów. W tym celu należy wykonać start transakcji z parametrem TransactionSettlementMode o wartości NONE oraz Amount wskazującym kwotę zasilenia.

Skorzystanie z Przedtransakcji pozwoli na proste dostarczenie gotowej transakcji do płatnika (np. podając w CustomerEmail adres księgowości Partnera).

UWAGA: Usługa musi zostać uzgodnienia z opiekunem biznesowym. W modelu Marketplace konieczne będzie ponadto zbudowanie koszyka produktów wskazującego jaki Punkt Rozliczeń (BalancePointID) ma zostać zasilony.

Wypłaty z salda

Opis

Dla serwisów posiadających saldo w Systemie, możliwe jest wykonanie operacji wypłaty całości bądź części salda na zdefiniowany rachunek do rozliczeń. W tym celu należy wywołać metodę balancePayoff (https://{host_bramki}/settlementapi/balancePayoff) z odpowiednimi parametrami.

Wszystkie parametry przekazywane są metodą POST (Content-Type: application/x-www-form-urlencoded). Protokół rozróżnia wielkość liter zarówno w nazwach jak i wartościach parametrów. Wartości przekazywanych parametrów powinny być kodowane w UTF-8.

Lista dostępnych parametrów dla wypłat z salda

WAŻNE! Kolejność atrybutów do wyliczenia Hash musi być zgodna z ich numeracją.

UWAGA: Wymagane jedno z pól ServiceID lub BalancePointID.
Podanie obu spowoduje zatrzymanie przetwarzania żądania oraz błąd http.

Odpowiedź na żądanie

Po otrzymaniu żądania wypłaty z salda System wykonuje wstępną weryfikację pod kątem przesłanych w komunikacie pól i ich wartości oraz zapisuje zlecenie do wykonania. W odpowiedzi na żądanie zwracany jest (w tej samej sesji HTTP) tekst w formacie XML, zawierający potwierdzenie zapisania zlecenia w kolejce do wykonania lub opis błędu(struktura komunikatu błędu opisana w części Komunikaty błędu.

UWAGA: Potwierdzenie przyjęcia zlecania nie jest równoznaczne z faktycznym jego wykonaniem. Wypłata z salda może być realizowana do 30 minut od momentu wysyłki żądania wypłaty i nie zawsze może się zakończyć sukcesem. W przypadku problemów napotkanych podczas procesowania wypłaty z salda (np. niewystarczające środki na saldzie) następnego dnia roboczego wysyłany jest raport zawierający informację o wypłatach z salda, które nie doszły do skutku.

Struktura potwierdzenia (XML)

	<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
	<balancePayoff>
		<serviceID>ServiceID</serviceID>
		<messageID>MessageID</messageID>
		<hash>Hash</hash>
	</balancePayoff>

lub

	<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
	<balancePayoff>
		<balancePointID>BalancePointID</balancePointID>
		<messageID>MessageID</messageID>
		<hash>Hash</hash>
	</balancePayoff>

Opis pól

WAŻNE! Kolejność atrybutów do wyliczenia Hash musi być zgodna z ich numeracją.

UWAGA: Za błąd uznać można wszystkie odpowiedzi inne niż założona (tj. z niepoprawnymi polami, w szczególności pustym lub niepoprawnym hash). W przypadku, gdy System zautoryzuje nadawcę komunikatu zwrotu, jednak nie uda się wykonać operacji, odpowiedź będzie zgodna ze schematem opisanym w części Komunikaty błędu. W przypadku błędu komunikacji lub braku wystarczającego salda (np. ON_DEMAND_ERROR) można ponowić zlecenie. W przypadku blokady salda (BALANCE_DISABLED) lub nieaktywnej konfiguracji (PARTNER_DISABLED) nie należy ponawiać zlecenia.

WAŻNE! W przypadku błędu zwróconego w odpowiedzi na żądanie wypłaty z salda można ponowić zlecenie, należy jednak pamiętać o tym, że każde zlecenie wypłaty nie kończące się błędem może zostać wykonane. W przypadku problemów z połączeniem, przekroczenia maksymalnego czasu oczekiwania na odpowiedź, żądanie może zostać ponowione z tym samym MessageID bez obawy o zduplikowanie zlecenia.
W przypadku blokady salda (BALANCE_DISABLED) lub nieaktywnej konfiguracji (PARTNER_DISABLED) nie należy ponawiać zlecenia. 3 błędy pod rząd (bez względu na przyczynę) powodują blokadę usługi wypłat na żądanie dla określonego IP nadawcy komunikatu na 10 minut – wywołania w tym czasie dla tego IP będą kończyć się błędem TEMPORARY_DISABLED.

Zwroty transakcji

Opis

Dla serwisów posiadających saldo w Systemie, możliwe jest wykonanie operacji zwrotu do Klienta całości bądź części kwoty wpłaconej na rzecz wskazanej transakcji. Skuteczny zwrot całości transakcji można wykonać jeden raz (w przypadku ponownej próby zlecenia zwrotu tej samej transakcji, System zwraca odpowiednio opisany błąd). Zwroty części kwoty transakcji można na niej wykonywać wiele razy, o ile ich suma nie przekroczy kwoty wpłaty.

Aby wykonać zwrot transakcji, należy wywołać metodę transactionRefund (https://{host_bramki}/settlementapi/transactionRefund) z odpowiednimi parametrami. Wszystkie parametry przekazywane są metodą POST (Content-Type: application/x-www-form-urlencoded). Protokół rozróżnia wielkość liter zarówno w nazwach jak i wartościach parametrów. Wartości przekazywanych parametrów powinny być kodowane w UTF-8.

Lista dostępnych parametrów

WAŻNE! Kolejność atrybutów do wyliczenia Hash musi być zgodna z ich numeracją.

W odpowiedzi na żądanie zwracany jest (w tej samej sesji HTTP) tekst w formacie XML, zawierający potwierdzenie wykonania operacji lub opis błędu (opis poniżej).

Struktura potwierdzenia (XML)

	<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
	<transactionRefund>
		<serviceID>ServiceID</serviceID>
		<messageID>MessageID</messageID>
		<hash>Hash</hash>
	</transactionRefund>

Opis pól

WAŻNE! Kolejność atrybutów do wyliczenia Hash musi być zgodna z ich numeracją.

Opcja wykonywania zwrotów do opłaconych transakcji możliwa jest do 12 miesięcy wstecz, licząc od daty rozpoczęcia transakcji. Wyjątek stanowią płatności BLIK, które ze względu na ograniczenia czasowe po stronie dostawcy Kanału płatności, można zwracać do 6 miesięcy wstecz.

Powyższe terminy dotyczą realizowania zwrotów poprzez panel administracyjny oraz transactionRefund, np. za pośrednictwem własnych narzędzi administracyjnych. Po ich przekroczeniu zostanie zwrócony błąd (TRANSACTION_TOO_OLD_TO_REFUND). Schemat działania jest analogiczny jak w przypadku wypłat z salda. To znaczy, że System przyjmuje zlecenie i asynchronicznie przetwarza je w ciągu maksymalnie 30 minut, a w przypadku niepowodzenia informacja o operacjach zakończonych błędem jest wysyłana w raporcie następnego dnia roboczego.

W przypadku problemów z połączeniem, przekroczenia maksymalnego czasu oczekiwania na odpowiedź, żądanie może zostać ponowione z tym samym MessageID bez obawy o zduplikowanie zlecenia. Za błąd uznać można wszystkie odpowiedzi inne niż założona (tj. z niepoprawnymi polami, w szczególności pustym lub niepoprawnym hash). W przypadku, gdy System zautoryzuje nadawcę komunikatu zwrotu, jednak nie uda się wykonać operacji, w odpowiedzi zwrócony zostanie komunikat błędu.

Zwroty produktu

Opis

Dla serwisów posiadających saldo w Systemie oraz podających w koszyku produktów parametr productID, możliwe jest wykonanie operacji zwrotu do Klienta całości, bądź części kwoty wpłaconej na rzecz wskazanego produktu. Skuteczny zwrot całości kwoty produktu można wykonać jeden raz (w przypadku ponownej próby zlecenia zwrotu tego samego produktu, System zwraca odpowiednio opisany błąd). Zwroty części kwoty produktu można na nim wykonywać wiele razy, o ile ich suma nie przekroczy kwoty wpłaconej na rzecz produktu.

Aby wykonać zwrot produktu, należy wywołać metodę productRefund (https://{host_bramki}/settlementapi/productRefund) z odpowiednimi parametrami. Wszystkie parametry przekazywane są metodą POST (Content-Type: application/x-www-form-urlencoded). Protokół rozróżnia wielkość liter zarówno w nazwach jak i wartościach parametrów. Wartości przekazywanych parametrów powinny być kodowane w UTF-8.

Lista parametrów

WAŻNE! Kolejność atrybutów do wyliczenia Hash musi być zgodna z ich numeracją.

Odpowiedź na żądanie

W odpowiedzi na żądanie zwracany jest (w tej samej sesji HTTP) tekst w formacie XML, zawierający potwierdzenie wykonania operacji lub opis błędu (opis poniżej).

Struktura potwierdzenia (XML)

	<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
	<productRefund>
		<serviceID>ServiceID</serviceID>
		<messageID>MessageID</messageID>
		<hash>Hash</hash>
	</productRefund>

Opis pól

WAŻNE! Kolejność atrybutów do wyliczenia Hash musi być zgodna z ich numeracją.

Opcja wykonywania zwrotów do opłaconych transakcji możliwa jest do 12 miesięcy wstecz, licząc od daty rozpoczęcia transakcji. Wyjątek stanowią płatności BLIK, które ze względu na ograniczenia czasowe po stronie dostawcy Kanału płatności, można zwracać do 6 miesięcy wstecz.

Powyższe terminy dotyczą realizowania zwrotów poprzez panel administracyjny oraz productRefund, np. za pośrednictwem własnych narzędzi administracyjnych. Po ich przekroczeniu zostanie zwrócony błąd (TRANSACTION_TOO_OLD_TO_REFUND). Schemat działania jest analogiczny jak w przypadku wypłat z salda. To znaczy, że System przyjmuje zlecenie i asynchronicznie przetwarza je w ciągu maksymalnie 30 minut, a w przypadku niepowodzenia informacja o operacjach zakończonych błędem jest wysyłana w raporcie następnego dnia roboczego.

W przypadku problemów z połączeniem, przekroczenia maksymalnego czasu oczekiwania na odpowiedź, żądanie może zostać ponowione z tym samym MessageID bez obawy o zduplikowanie zlecenia. Za błąd uznać można wszystkie odpowiedzi inne niż założona (tj. z niepoprawnymi polami, w szczególności pustym lub niepoprawnym hash). W przypadku, gdy System zautoryzuje nadawcę komunikatu zwrotu, jednak nie uda się wykonać operacji, w odpowiedzi zwrócony zostanie komunikat błędu (Zob. Komunikaty błędu).

Odpytanie o status zwrotu lub wypłaty z salda

Opis

Po wykonaniu zwrotu lub wypłaty z salda mamy możliwość weryfikacji w jakim statusie jest transakcja rozliczeniowa oraz jaki został jej nadany identyfikator przez System płatności online. W tym celu należy wywołać metodę outDetails (https://{host_bramki}/settlementapi/outDetails) z odpowiednimi parametrami.

Wszystkie parametry przekazywane są metodą POST (Content-Type: application/x-www-form-urlencoded). Protokół rozróżnia wielkość liter zarówno w nazwach jak i wartościach parametrów. Wartości przekazywanych parametrów powinny być kodowane w UTF-8.

Lista dostępnych parametrów dla wypłat z salda

WAŻNE! Kolejność atrybutów do wyliczenia Hash musi być zgodna z ich numeracją.

UWAGA: Wymagane jedno z pól ServiceID lub BalancePointID.
Podanie obu spowoduje zatrzymanie przetwarzania żądania oraz błąd http.

Odpowiedź na żądanie

Struktura potwierdzenia (XML)

	<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
	<outDetails>
		<serviceID>ServiceID</serviceID>
		<messageID>MessageID</messageID>
	  	<status>Status</status>
		<remoteOutId>RemoteOutId</remoteOutId>
		<hash>Hash</hash>
	</outDetails>

lub

	<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
	<outDetails>
		<balancePointID>BalancePointID</balancePointID>
		<messageID>MessageID</messageID>
		<status>Status</status>
		<remoteOutId>RemoteOutId</remoteOutId>
		<hash>Hash</hash>
	</outDetails>

Opis pól

WAŻNE! Kolejność atrybutów do wyliczenia Hash musi być zgodna z ich numeracją.

Strona podsumowania transakcji

Opis

System umożliwia wyświetlanie Klientowi podsumowania transakcji. W tym celu Partner może budować linki uruchamiające z odpowiednimi parametrami metodę confirmation (https://{host_bramki}/confirmation/payment). Wszystkie parametry przekazywane są metodą GET. Protokół rozróżnia wielkość liter zarówno w nazwach jak i wartościach parametrów. Wartości przekazywanych parametrów powinny być kodowane w UTF-8.

Lista parametrów dla metody podsumowania transakcji

Przekierowanie Klienta z poprawnymi parametrami spowoduje wyświetlenie podsumowania transakcji (o treści zależnej od jej stanu) lub informacji o jej braku (jeśli System nie jej nie odnajdzie).

WAŻNE! Kolejność atrybutów do wyliczenia Hash musi być zgodna z ich numeracją.

UWAGA: Usługa musi zostać aktywowana po uzgodnieniu z opiekunem biznesowym. Istnieje możliwość zmiany treści komunikatów lub dostosowanie szaty graficznej (podlegają one każdorazowo ustaleniom w formie roboczej podczas integracji).

Odpytanie o status transakcji

Opis

Dla wszystkich serwisów możliwe jest odpytanie o status transakcji. W tym celu należy wywołać metodę transactionStatus (https://{host_bramki}/webapi/transactionStatus) z odpowiednimi parametrami.

Wszystkie parametry przekazywane są metodą POST (Content-Type: application/x-www-form-urlencoded). Protokół rozróżnia wielkość liter zarówno w nazwach jak i wartościach parametrów. Wartości przekazywanych parametrów powinny być kodowane w UTF-8.

Lista parametrów dostępnych dla statusu transakcji

WAŻNE! Kolejność atrybutów do wyliczenia Hash musi być zgodna z ich numeracją.

Nagłówek HTTP dla zapytania o status transakcji

Do poprawnego odpytania należy, wraz z przekazywanymi parametrami, przesłać zdefiniowany nagłówek HTTP o odpowiedniej treści. Dołączony nagłówek powinien nosić nazwę 'BmHeader' i posiadać następującą wartość 'pay-bm', w całości powinien prezentować się następująco 'BmHeader: pay-bm'. W przypadku poprawnego komunikatu zwracany jest (w tej samej sesji HTTP) tekst w formacie XML, zawierający wszystkie transakcje o wskazanym OrderID wraz z podstawowymi o nich informacjami.

WSKAZÓWKA: Sytuacja taka może mieć miejsce np. w przypadku, gdy Klient zmieni Kanał Płatności, wywoła ponownie ten sam start transakcji z historii przeglądarki itp. System umożliwia blokowanie takich przypadków, jednak opcja nie jest zalecana (nie byłoby możliwe opłacenie porzuconej transakcji).

WAŻNE! W przypadku gdy odpytanie dotyczy orderID, które występuje w ponad 50 transakcjach danego serwisu, zwracana jest odpowiedź (XML) z kodem błędu 403.

Struktura odpowiedzi w przypadku osiągniętego limitu transakcji z tym samym orderId:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<transaction>
    <reason>LIMIT_REQUESTED_TRANSACTIONS_WITH_THE_SAME_ORDER_ID_AND_SERVICE_ID_EXCEEDED</reason>
    <description>Transaction limit 50 with the same order id {{ORDER_ID}} and service id {{SERVICE_ID}} exceeded. Requested count {{TRANSACTION_AMOUNT}}
    </description>
</transaction>

Lista pól dla zapytania o status transakcji

WAŻNE! Kolejność atrybutów do wyliczenia Hash musi być zgodna z ich numeracją.

UWAGA: Ponieważ metoda może zwrócić wiele transakcji, do Hash pobierane są kolejne transakcje (zgodnie z kolejnością występowania transakcji w odpowiedzi). W ramach danej transakcji zastosowanie ma kolejność zgodna z numerem obok pola (z wyłączeniem parametru ServiceID, poziom wyżej).

Przykład łańcucha funkcji skrótu

		Hash = funkcja(<serviceID> + „|” +
	<orderID1> + „|” + <remoteID1> + „|” + <amount1> + „|” + <currency1> + „|” + <gatewayID1> + „|” + <paymentDate1> + „|” + <paymentStatus1> + „|” + <paymentStatusDetails1> + „|” +
	<orderID2> + „|” + <remoteID2> + „|” + <amount2> + „|” + <currency2> + „|” + <gatewayID2> + „|” + <paymentDate2> + „|” + <paymentStatus2> + „|” + <paymentStatusDetails2> + …

Obsługa odpowiedzi zapytania o status transakcji - propozycja obsługi wielu transakcji w odpowiedzi

Anulowanie nieopłaconej transakcji

Opis anulowania nieopłaconej transakcji

Dla wszystkich serwisów możliwe jest anulowanie rozpoczętej, ale nieopłaconej transakcji poprzez wywołanie metody transactionCancel (https://{host_bramki}/webapi/transactionCancel) z odpowiednimi parametrami. Wszystkie parametry przekazywane są metodą POST (Content-Type: application/x-www-form-urlencoded).

Protokół rozróżnia wielkość liter zarówno w nazwach jak i wartościach parametrów. Wartości przekazywanych parametrów powinny być kodowane w UTF-8.

Lista parametrów dostępnych dla anulowania nieopłaconej transakcji

WAŻNE! Kolejność atrybutów do wyliczenia Hash musi być zgodna z ich numeracją.

Nagłówek dla anulowania nieopłaconej transakcji

Do poprawnego odpytania należy, wraz z przekazywanymi parametrami, przesłać zdefiniowany nagłówek HTTP o odpowiedniej treści. Dołączony nagłówek powinien nosić nazwę 'BmHeader' i posiadać następującą wartość 'pay-bm'. W całości powinien prezentować się następująco:

'BmHeader: pay-bm'

W przypadku poprawnego komunikatu zwracany jest (w tej samej sesji HTTP) tekst w formacie XML, zawierający potwierdzenie wykonania operacji lub opis błędu.

Struktura potwierdzenia (XML)

	<?xml version="1.0" encoding="UTF-8"?>
	<transaction>
		<serviceID>ServiceID</serviceID>
		<messageID>MessageID</messageID>
		<confirmation>ConfStatus</confirmation>
		<reason>Reason</reason>
		<hash>Hash</hash>
	</transaction>

Lista parametrów dla anulowania nieopłaconej transakcji

WAŻNE! Kolejność atrybutów do wyliczenia Hash musi być zgodna z ich numeracją.

Odpowiedzi na żądania anulowania transakcji

Jeśli komunikat jest poprawny składniowo, System zwróci jedną z poniższych par opisujących wynik przetwarzania. Poza jej interpretacją, zaleca się kontrolnie odpytać o status transakcji (metoda transactionStatus).

Należy pamiętać, że po skutecznym anulowaniu przynajmniej jednej transakcji, nie jest możliwe wystartowanie nowej, ani kontynuowanie wcześniej wystartowanej transakcji o tym samym OrderID.

Komunikaty błędu

Opis komunikatów błędu

Wszystkie komunikaty błędów będą zwracane w postaci dokumentu XML, zawierającego kod błędu, jego nazwę oraz opis. Ze względu na dużą zmienność możliwych błędów, nie jest utrzymywana pełna dokumentacja błędów.

WSKAZÓWKA: Pole description, dokładnie opisuje każdy z błędów (pola statusCode i name mogą być ignorowane).

Przykładowy błąd (XML)

	<?xml version="1.0" encoding="UTF-8"?>
	<error>
		<statusCode>55</statusCode>
		<name>BALANCE_ERROR</name>
		<description>Wrong services balance! Should be 100 but is 40</description>
	</error>

Schematy obsługi transakcji i rozliczeń

W tej części przedstawione są modele, scenariusze zdarzeń i przepływu informacji.

Rozszerzona struktura serwisów i punktów rozliczeń

Struktura Partnera składa się z przynajmniej 1 serwisu (identyfikowane za pomocą identyfikatora ServiceID) oraz dowolnej liczny punktów rozliczeń (identyfikowane za pomocą identyfikatora idBalancePoint).

• Serwisami są zazwyczaj źródła Linków Płatności (strona WWW, aplikacja mobilna, maile itp). Serwisy też rozdzielają ruch dotyczący różnych branż (płatności za faktury, zakupy e-Commerce itp.). Ponieważ transakcja identyfikowana jest przez parę OrderID i ServiceID, można powiedzieć, że „serwis odpowiada poziomowi transakcji".

• Punkty rozliczeń definiuje się, jeśli istnieje potrzeba rozróżnienia w jakiś sposób składowych płatności (np. poprzez wskazanie ich w raportach lub niezależne rozliczenie). Ponieważ produkt transakcji identyfikowany jest przez przynależący mu punkt rozliczeń (idBalancePoint), można powiedzieć, że „punkt rozliczeń odpowiada poziomowi produktu".

Koszyk produktów (a więc również punkty rozliczeń) może nie występować w strukturze opisującej Partnera. Przyczyna dodania do struktury punktów rozliczeń wpływa na decyzję o modelu rozliczeniowym:

• potrzeba rozróżnienia składowych wpłaty na liście transakcji (w raportach) niekoniecznie musi pociągać za sobą osobnego rozliczania każdego z produktów lub punktów rozliczeń; w tej sytuacji zazwyczaj w zupełności wystarczają modele rozliczeniowe na poziomie serwisu (zbiorcze lub po każdej wpłacie)

• potrzeba rozdzielenia rozliczeń składowych wpłaty, powoduje zastosowanie modelu rozliczeniowego na poziomie punktu rozliczeń (zbiorcze lub po każdej wpłacie).

Poniżej ilustracja przykładowej struktury (bez wskazywania konkretnego modelu rozliczeniowego)

Modele rozliczeń

Model rozliczeń zbiorczych transakcji (model domyślny)

Rozliczenia zbiorcze następują następnego dnia roboczego (D+1).

Model rozliczeń transakcji po każdej wpłacie

Rozliczenia po każdej wpłacie wykonywane mogą być niezwłocznie po otrzymaniu wpłaty od Klienta na wskazane w parametrach Linka płatności dane transakcji (opcje: Konto odbiorcy, Tytuł przelewu rozliczeniowego, Nazwa odbiorcy przelewu rozliczeniowego).

Model rozliczeń zbiorczych produktów

Rozliczenia zbiorcze następują następnego dnia roboczego (D+1).

Model rozliczeń produktów po każdej wpłacie

Rozliczenia po każdej wpłacie wykonywane mogą być niezwłocznie po otrzymaniu wpłaty od Klienta na wskazane w parametrach Linka płatności dane produktu (opcje: Konto odbiorcy, Tytuł przelewu rozliczeniowego, Nazwa odbiorcy przelewu rozliczeniowego).

Model rozliczeń transakcji na żądanie

Rozliczenia mogą być zlecane przez Partnera poprzez wywołanie metody: transactionSettlement.