DOKUMENTACJA TECHNICZNA DLA ŚRODOWISKA TESTÓW INTEGRACYJNYCH API PKO BANKU POLSKIEGO

Transkrypt

1 DOKUMENTACJA TECHNICZNA DLA ŚRODOWISKA TESTÓW INTEGRACYJNYCH API PKO BANKU POLSKIEGO Streszczenie dokumentacji wersja 1.0 z dn r. Spis treści Spis treści... 1 Rozdział 1. Wstęp... 2 Rozdział 2. Podstawowe informacje dotyczące Sandboxa... 2 Rozdział 3. Jak rozpocząć korzystanie z Sandbox API PKO Banku Polskiego?... 2 Rozdział 4. Usługi autoryzacji i zarządzania zgodą... 3 Rozdział 5. Usługi inicjacji płatności (PIS)... 3 Rozdział 6. Usługi informacji o rachunku (AIS)... 4 Rozdział 7. Usługi weryfikacji dostępności środków płatniczych (CAF)... 4 Rozdział 8. Różnice między PolishAPI a API PKO Banku Polskiego S.A Podsumowanie... 5

2 Rozdział 1. Wstęp Celem tej dokumentacji jest opisanie sposobu w jaki developerzy mogą połączyć się z API (ang. Application Programming Interface) udostępnionym przez PKO Bank Polski. Zawartość dokumentacji będzie aktualizowana wraz z powstawaniem nowych wersji środowiska testów integracyjnych API (Sandbox), odzwierciedlających postępy procesu testowania i uwzględniających uwagi TPP (ang. Third Party Providers) Zanim rozpoczniesz proces developmentu/testowania zapoznaj się z Regulaminem świadczenia usług drogą elektroniczną przez PKO Bank Polski w zakresie Otwartej Bankowości PKO Banku Polskiego, dostępnym pod adresem Nasze API jest oparte na standardzie PolishAPI, chcąc zobaczyć pełną dokumentację standardu PolishAPI przejdź na stronę: Dane testowe są udostępniane poprzez skorzystanie z serwisu Sandbox. Można z niego skorzystać po ukończeniu procesu weryfikacji. W tym celu należy uzupełnić formularz dostępny na stronie Rozdział 2. Podstawowe informacje dotyczące Sandboxa Zadaniem środowiska testów integracyjnych API jest możliwość przetestowania funkcjonalności API oraz podłączenia i przetestowania swojej aplikacji wykorzystywanej do oferowania usług płatniczych, o których mowa w 10, 12, 13 i Dostęp do środowiska testowego Sandbox nie umożliwia dostępu do danych produkcyjnych istniejących w banku. Celem środowiska testowego jest odwzorowanie i zasymulowanie usług wystawionych na produkcji. Na potrzeby środowiska testowego zostały udostępnione fikcyjne dane testowe, które odwzorują strukturę danych produkcyjnych w możliwie najlepszy sposób, ale nie mają pokrycia w danych rzeczywistych klientów. 7. Aby rozpocząć proces korzystania z API Sandbox należy przesłać wniosek o dostęp. Formularz wniosku znajduje się na stronie Po prawidłowym wypełnieniu formularza, przedstawiciel banku dokonuje weryfikacji zgłoszenia, a następnie wysyła prośbę do TPP o przesłanie części publicznej certyfikatu eidas zgodnego z normą ETSI TS , oraz udowodnienia posiadania klucza prywatnego korespondującego z tym certyfikatem (PKO Bank Polski pomoże w procesie przeprowadzenia tego dowodu, jeśli TPP będzie miał wątpliwości). Jest to warunek niezbędny do korzystania z API Sandbox. Podmioty będące w trakcie ubiegania się o licencję TPP mogą wystąpić o dostep do sandbox używając certyfikatów testowych. Po przesłaniu przez klienta certyfikatu następuje proces weryfikacji. W przypadku jakichkolwiek wątpliwości, bank zastrzega sobie prawo do wstrzymania dalszego procesu weryfikacji, do czasu wyjaśnienia wątpliwości. W następnym kroku firma zostanie dodana do wewnętrznej, bankowejbazy TPP i zostaną dla niej utworzone dostępy, które pozwolą na testowanie usług API banku na środowisku testowym. Po zakończeniu procesu firma aplikująca o dostęp do Sandboxa otrzyma od nas a powiadamiającego o pozytywnej weryfikacji. 8. Komunikacja z Sandboxem: TLS (ang. Transport Layer Security) przyjęte jako standard w Internecie rozwinięcie protokołu SSL (ang. Secure Socket Layer). TLS zapewnia poufność i integralność transmisji danych, a także uwierzytelnienie serwera, a niekiedy również klienta. Opiera się na szyfrowaniu asymetrycznym oraz certyfikatach X.509. Certyfikaty SSL są narzędziem zapewniającym ochronę witryn internetowych, a także gwarantem zachowania poufności danych przesyłanych drogą elektroniczną. Pełne bezpieczeństwo jest efektem zastosowania szyfrowania komunikacji pomiędzy komputerami. Certyfikaty SSL rejestrowane są na określoną nazwę domeny, zawierają informacje o właścicielu domeny, jego adresie itp. Dane te są zabezpieczone kryptograficznie i nie można ich samodzielnie zmienić. Certyfikaty pieczęci - pieczęć elektroniczna to usługa zaufania służąca do potwierdzania autentyczności i tożsamości wystawcy dokumentów elektronicznych. Rozwiązanie wykorzystuje kwalifikowany certyfikat pieczęci elektronicznej, który w odróżnieniu od podpisu elektronicznego, nie zawiera danych osoby fizycznej, a jedynie dane podmiotu posiadającego osobowość prawną (tj. firmy, organizacji, podmiotu administracji publicznej). Pieczęć elektroniczna to efektywne narzędzie zapewniające: Integralność zabezpieczenie danych oraz dokumentów elektronicznych przed zmianą Wiarygodność identyfikacja tożsamości przedsiębiorstwa /organizacji w świecie elektronicznym Niezaprzeczalność brak możliwości wyparcia się procesu pieczętowania Certyfikaty pieczęci są zgodne z europejskim rozporządzeniem eidas Usługa jest zgoda z europejskim rozporządzeniem eidas, dzięki czemu dokumenty opieczętowane pieczęcią elektroniczną zachowują pełną moc prawną oraz dowodową Rozdział 3. Jak rozpocząć korzystanie z Sandbox API PKO Banku Polskiego? 9. Po pozytywnej weryfikacji TPP otrzyma od nas dane (indywidualny identyfikator, dalej: clientid) oraz pełną dokumentację techniczną, która pozwoli na korzystanie z API. Proces autoryzacji jest pierwszą czynnością, która pozwala na otrzymanie przez TPP tokenu wymaganego do wywoływania usług Sandbox pełna dokumentacja zawiera szczegółowy opis kroków w tym procesie, wraz z ilustracjami. Podążając za przedstawionym opisem, TPP będzie mógł dowiedzieć się, używając bezpośrednio dostarczonego API, o zakresie dostępnych danych testowych (w tym: identyfikatorach testowych klientów oraz ich rachunkach). Zdobycie tych danych pozwala na wywołanie bardziej zaawansowanych scenariuszy (takich jak np. ustalenie identyfikacji klienta po stronie TPP lub wybór rachunków objętych zgodą w scenariuszach z wyborami klienta i rachunków, dokonywanymi a priori po stronie TPP).

3 Ilustracją do instrukcji są przykładowe żądania, które po uzypełnieniu o dane identyfikacyjne TPP (tppid, clientid) mogą zostać bezpośrednio wywołane. Rozdział 4. Usługi autoryzacji i zarządzania zgodą Usługi autoryzacji pozwalają na wyrażenie (delegację) zgody klienta banku na dostęp do operacji na rachunku płatniczym na rzecz TPP. Zaimplementowano usługi z rodziny Polish API, będące wariantem usług z grupy OAuth 2.0, oraz usługę odwołania zgody. 10. Do realizacji powyższych funkcji wykorzystano usługi API zgodne ze standardem Polish API (na dzień wydania tego dokumentu zaimplementowana została wersja standardu 2.1.1). Zaimplementowano operacje wymienione poniżej: Autoryzacja działań na rachunku Pobranie tokenu autoryzacyjnego lub odświeżenie tokenu, dla wyrażonej zgody Odwołanie zgody (poinformowanie banku o odwołaniu zgody) authorize token deleteconsent Rozdział 5. Usługi inicjacji płatności (PIS) 11. Usługa inicjowania transakcji płatniczej (PIS) polega na udostępnieniu przez PKO Bank Polski możliwości zainicjowania płatności z rachunku płatniczego dostępnego online, przez użytkowników bankowości PKO Banku Polskiego, za pośrednictwem dostawcy będącego stroną trzecią (TPP), występującego w roli Payment Initiation Service Provider (PISP), po uprzednim pozyskaniu odpowiednich zgód od użytkownika. 12. W ramach usługi PIS PKO Bank Polski umożliwia inicjację płatności typu: a) przelew zwykły krajowy (Elixir, ExpressElixir, Sorbnet, wewnętrzny) b) przelew zagraniczny EEA (TARGET oraz SEPA) oraz non-eea (SWIFT) c) zlecenia stałe d) przelew podatkowy krajowy e) paczkę przelewów Do realizacji powyższej funkcji wykorzystano usługi API zgodne ze standardem Polish API (na dzień wydania tego dokumentu zaimplementowana została wersja standardu 2.1.1). Zaimplementowano nastepujący zestaw operacji: Inicjacja przelewu krajowego domestic Wspierane systemy rozliczeń: Elixir, ExpressElixir, Sorbnet, wewnętrzny Inicjacja krajowego przelewu podatkowego tax Wspierane systemy rozliczeń: Elixir, ExpressElixir Inicjacja przelewu europejskiego EEA Wspierane systemy rozliczeń: TARGET, instantsepa oraz SEPA Inicjacja przelewu zagranicznego pozaeuropejskiego noneea Wspierane systemy rozliczeń: SWIFT Sprawdzenie statusu przelewu getpayment Dla wszystkich rodzajów przelewów Odwołanie przelewu z datą przyszłą lub paczki przelewów cancelpayments Istnieje możliwość odwołania płatności z datą przyszłą, w tym odwołanie płatności wielokrotnej (paczki przelewów), z zastrzeżeniem, że jeżeli w momencie odwołania w skład paczki wchodzą przelewy już wykonane, to odwołanie nie ma na nie wpływu i odwołanie skutkuje niewykonaniem wyłącznie płatności z datą przyszłą Zlecenia stałe recurring Zlecenie stałe może dotyczyć dowolnego rodzaju wspieranego przelewu Sprawdzenie statusu zlecenia stałego Odwołanie zlecenia stałego getrecurringpayment cancelrecurringpayment Zlecenie paczki przelewu bundle Możliwość zlecenia paczki przelewów z tego samego rachunku. W paczce znajdować się mogą przelewy tego samego typu (dowolnego ze

4 wspieranych) Sprawdzenie statusu paczki przelewów Sprawdzenie statusu wielu przelewów getbundle getmultiplepayments Rozdział 6. Usługi informacji o rachunku (AIS) 13. Usługa dostępu do informacji o rachunku (AIS) polega na udostępnieniu przez PKO Bank Polski danych dotyczących historii transakcji oraz wybranych informacji dotyczących rachunku płatniczego, do którego użytkownik bankowości PKO Banku Polskiego posiada aktywny dostęp online. Dostęp udzielany jest dla TPP występującego jako Account Information Service Provider (AISP), po uprzednim pozyskaniu odpowiednich wyraźnych zgód użytkownika. Ponadto PKO Bank Polski udostępnia mechanizmy filtrowania danych, zgodnie z kryteriami dostępnymi online w bankowości elektronicznej. Do realizacji powyższych funkcji wykorzystano usługi API zgodne ze standardem Polish API (na dzień wydania tego dokumentu zaimplementowana została wersja standardu 2.1.1). Zaimplementowano następujący zestaw operacji: Pobranie listy rachunków Pobranie szczegółowych informacji o rachunku, w tym sald księgowego i dostępnego Pobranie historii operacji zaksięgowanych Pobranie historii operacji odrzuconych Pobranie historii operacji odwołanych Pobranie historii operacji oczekujących Pobranie historii operacji zaplanowanych Pobranie listy blokad na rachunku Pobranie szczegółowych informacji o transakcji getaccounts getaccount gettransactionsdone gettransactionsrejected gettransactionscancelled gettransactionspending gettransactionsscheduled getholds gettransactiondetails Rozdział 7. Usługi weryfikacji dostępności środków płatniczych (CAF) 14. Usługa potwierdzania dostępności na rachunku płatnika kwoty niezbędnej do wykonania transakcji płatniczej (CAF) polega na przesłaniu zapytania przez TPP, występującego w roli Card-based Payment Instrument Issuer (CBPII) do PKO Banku Polskiego. Zapytanie to ma na celu potwierdzenie czy na danym rachunku, dostępnym online, użytkownika bankowości PKO Banku Polskiego znajdują się środki w określonej w zapytaniu kwocie., Realizacja zapytania jest możliwa na podstawie zgody uprzednio udzielonej przez użytkownika. W odpowiedzi bank zwraca odpowiedź będącą komunikatem TAK albo NIE. Do realizacji powyższych funkcji wykorzystano usługę API zgodną ze standardem Polish API (na dzień wydania tego dokumentu zaimplementowana została wersja standardu 2.1.1). Zaimplementowano poniższą operację: Weryfikacja dostępności środków na rachunku getconfirmationoffunds Rozdział 8. Różnice między PolishAPI a API PKO Banku Polskiego S.A. 15. Opieramy się na standardzie PolishAPI, jednak wprowadziliśmy nieznaczne modyfikacje, adaptujące do specyfiki banku, oraz ułatwiające użycie API. W szczególności: 1. Wprowadziliśmy wymagalność wybranych pól, niezbędnych do realizacji usług w systemach banku, a w standardzie opisanych jako opcjonalne. Np.: wymagamy podania identyfikatora TPP w nagłówku wywołań API oraz podania identyfikacji płatności przez stronę zlecającą w zleceniach inicjacji płatności itp. 2. Uściśliliśmy interpretacje pozwoleń odnoszących się do zakresów dat (maxallowedhistorylong) poprzez aplikację kontekstowo do różnego rodzaju dat, np: daty księgowania dla transakcji wykonanych, daty zlecenia dla transakcji odrzuconych i odwołanych itp. 3. W przypadkach gdy wewnętrzne systemy banku nie wspierają wybranych funkcjonalności, zawęziliśmy explicite dozwolone parametry usług. 4. Zapewniliśmy jednoznaczność intencji wywołania API, szczególnie w autoryzacji, poprzez uzupełnienie wartościami domyślnymi w razie nie podania ich przez TPP i podanie ich jako informacji zwrotnej z usług autoryzacji.

5 Podsumowanie Cieszymy się, że jesteście zainteresowani naszymi usługami. Dołożymy wszelkich starań, by integracja Waszej aplikacji z naszym API przebiegła bez żadnych problemów. Jeśli chcecie uzyskać dalsze informacje zapraszamy do kontaktu poprzez stronę