1. Zostań TPP

Aby móc korzystać z API udostępnionych dzięki PSD2 musisz zostać TPP (Third Party Provider) w rozumieniu PSD2. W tym celu złóż wniosek o rejestrację w instytucji nadzorczej, odpowiedniej dla kraju w którym są wykonywane usługi.

Aby móc uzyskać pełny dostęp do dokumentacji zawartej w Portalu Developera oraz do środowiska Sandbox wystarczy, że rozpoczniesz procedurę rejestracji jako TPP i od tego momentu już możesz się rejestrować w Portalu Developera. W trakcie rejestracji w Portalu Developera będziesz potrzebował dokumentów potwierdzających fakt, że jesteś TPP lub starasz się o taki status.

2. Rejestracja w Portalu Developera

  1. Rejestracja TPP

1. Rozpocznij proces rejestracji korzystając z przycisku "Rejestracja" na głównej stronie Portalu Developera.
2. Podaj na stronie rejestracji dane reprezentowanej firmy, podaj Dane Administratora (TPP) oraz załącz następujące dokumenty:
   1. certyfikat QWAC PSD2, na podstawie którego weryfikowane są:
      • ważność certyfikatu
      • organ nadzoru
      • zgodność identyfikatora (NIP) z wartością podaną w formularzu
      • zakres usług PSD2 (PIS, AIS, CAF)
   2. dokumenty potwierdzające uprawnienia: link do rejestru uprawnień, skan uprawnień, skan potwierdzenia wniosku o uzyskanie statusu TPP.
3. Na adres email firmy otrzymasz powiadomienie o przyjęciu wniosku i rozpoczęciu procesu rejestracji.
4. Wniosek rejestracyjny zostanie zweryfikowany, a następnie:
   1. W przypadku pozytywnej weryfikacji, nasz Administrator aktywuje konto dla Administratora TPP zatwierdzając tym samym wniosek o rejestrację. Na podany adres email Administratora TPP zostanie wysłana wiadomość z linkiem do nadania hasła do serwisu. Oprócz tego na adres email firmy zostanie wysłana informacja o zakończeniu procesu rejestracji.
   2. W przypadku konieczności wyjaśnień na etapie rejestracji będziemy kontaktować się na adres email podany na stronie rejestracji.
   3. W przypadku odrzucenia wniosku rejestracyjnego na adres email firmy zostanie wysłana wiadomość z informacją o odmowie rejestracji.
5. Po pozytywnej weryfikacji TPP, Administrator TPP aktywuje konto i definiuje hasło dostępowe do swojego konta w Portalu Developera korzystając z linku, który otrzymał w wiadomości e-mail.
6. Logowanie do Portalu Developera odbywa się poprzez wprowadzenie wcześniej zdefiniowanego hasła. Od tego momentu Administrator TPP ma pełny dostęp do Portalu Developera

  2. Dodawanie developerów

Po rejestracji możesz dodać w ramach swojej firmy dodatkowych Developerów lub Administratorów. Mogą to robić użytkownicy z rolą Administrator. Taką rolę ma zawsze pierwszy użytkownik stworzony w ramach rejestracji.

W celu dodania nowego Developera:

1. Zaloguj się do Portalu Developera jako użytkownik, który ma rolę Administratora.
2. Przejdź do zakładki "Developerzy".
3. Wybierz przycisk "Dodaj developera", a następnie wypełnij następujące pola:
   1. E-mail - adres email nowego użytkownika, który będzie również jego loginem.
   2. Nazwa firmy - nazwa firmy, którą reprezentuje nowy użytkownik.
   3. Administrator - flaga określająca czy Developer będzie miał uprawnienia administracyjne, czyli uprawnienia do dodawania/edycji/usuwania użytkowników w Portalu Developera. (UWAGA: zaznaczenie flagi "Administrator" nowo dodawanemu Developerowi, sprawi, że nowy użytkownik będzie miał identyczne uprawnienia jak Administrator, który dodaje użytkownika.)
4. Zatwierdź dodawanie nowego użytkownika za pomocą przycisku "Zapisz".
5. Nowy użytkownik zostaje dodany, na jego adres e-mail jest wysyłana wiadomość powitalna z linkiem aktywacyjnym.
6. Nowy użytkownik po aktywacji konta i ustawieniu hasła, może logować się i korzystać ze wszystkich funkcjonalności Portalu Developera.

3. API

Nasze API bazuje na PolishAPI w wersji 2.1.2, którego dokumentację możesz pobrać ze strony https://polishapi.org/. Koniecznie zapoznaj się z dokumentacją PolishAPI, gdyż mechanizmy tam opisane dotyczą również naszego API.

Jest kilka różnic między PolishAPI a API wystawionym przez Bank:

• Nie obsługujemy autoryzacji EAT, w związku z tym brak jest metody /authorizeExt
• Nie ma metody /getMultiplePayments, możesz odpytywać pojedynczo o transakcje z użyciem metody /getPayment
• Wywołania zwrotne (callbacki) nie są obsługiwane, w związku z czym są drobne różnice w niektórych obiektach zapytań i odpowiedzi.
• W wywołaniach API nie możesz używać metod biznesowych i wartości słownikowych w parametrach, które dotyczą funkcjonalności niedostępnych w banku, mimo że są one dostępne w ogólnym PolishAPI. To, które dokładnie są dostępne możesz sprawdzić w swaggerowej dokumentacji naszego API.
• Certyfikat QSealC w zapytaniu musisz przekazać z użyciem atrybutu x5u w sygnaturze JWS, inne metody nie są wspierane. Atrybut x5u jest wymagany w każdym zapytaniu. W odpowiedzi certyfikat Banku będzie przekazany w atrybucie x5c.
• W zapytaniu /getTransactionDetail parametr bookingDate jest ignorowany. Aby wyszukać transakcję wystarczy podać jej identyfikator w atrybucie itemId.
• Metoda /cancelPayments pozwala anulować tylko transakcje, które są w statusie Scheduled. Do tej metody należy przekazać jeden z parametrów: paymentId lub bundleId. Przekazanie obu jest błędem.
• PolishAPI nie precyzuje niektórych aspektów dotyczących udzielania zgód, bardziej szczegółowy opis jest zawarty dalej w rozdziale „Reguły obsługi zgód”.

Możesz przeglądać i pobrać dokumentację naszego API w formacie Swagger po zalogowaniu się do Portalu Developera w zakładce "API" -> "Środowiska".

4. Sposób połączenia

  1. HTTPS

Dostęp do API odbywa się z użyciem protokołu HTTPS z certyfikatem klienta. Aby nawiązać połączenie musisz użyć certyfikatu transportowego Qualified Website Authentication Certificate (QWAC) zgodnego normą EIDAS. Certyfikaty transportowe służą do szyfrowania i uwierzytelniania komunikacji, zabezpieczają komunikacje między dwiema łączącymi się stronami.

Poniższa tabela przedstawia działanie certyfikatów QWAC w odniesieniu do warstw ISO/OSI.

Obsługiwany jest wyłącznie protokół TLS >= 1.2.

  2. Sygnatura JWS

Musisz podpisać dane wysyłane w zapytaniu, a Bank podpisze dane odpowiedzi. Podpis zapytania i odpowiedzi znajduje się w sygnaturze JWS w nagłówku HTTP o nazwie “X-JWS-SIGNATURE”.

Do generacji sygnatury JWS musisz użyć certyfikatu Qualified Electronic Seal Certificate (QsealC).

W przypadku PolishAPI do komunikacji są wymagane dwa osobne certyfikaty - QWAC i QSealC, nie jest dozwolone użycie jednego certyfikatu do obydwu zastosowań.

Sygnatura JWS składa się z trzech części: nagłówka, ciała i podpisu. Każda z części jest kodowana za pomocą Base64. Wszystkie części są rozdzielone od siebie za pomocą kropek. Ciało zawiera dokładnie te same informacje co ciało zapytania. Aby nie duplikować wysyłanych danych sygnatura JWS w PolishAPI jest w wersji „detached”, czyli nie zawiera części body.

Dokładny opis sygnatury JWS znajduje się w dokumencie RFC7515.

    1. Generacja

Do podpisu sygnatury potrzebny jest klucz prywatny certyfikatu QsealC.

Generowana sygnatura powinna zawierać adres certyfikatu. Powinien on znajdować się w nagłówku sygnatury o nazwie „x5u”. Inne metody przekazania certyfikatu w zapytaniu nie są wspierane. Certyfikat musisz udostępnić z użyciem protokołu HTTP lub HTTPS i domyślnych portów dla tych protokołów. Certyfikat musi być dostępny z Internetu, abyśmy mogli go pobrać i sprawdzić. Plik certyfikatu QSealC, do którego wskazuje się adres w sygnaturze JWS, powinien zawierać jeden certyfikat i mieć wielkość maksymalnie do 20KB.

W nagłówku sygnatury powinny znajdować się również kid, czyli identyfikator klucza oraz skrót certyfikatu. Kid jest używany do jednoznacznego zidentyfikowania klucza, jest on wysyłany w nagłówku sygnatury o nazwie „kid”. Skrót certyfikatu jest wysyłany w nagłówku „x5t#S256”. Dokładny opis obu nagłówków znajduje się w dokumencie RFC7515. Użycie obu nagłówków jest wymagane.

W przypadku PolishAPI używana jest kryptografia klucza publicznego. W związku z tym obsługiwane są następujące algorytmy w podpisie JWS:

•     RSA256
•     RSA384
•     RSA512
•     ECDSA256
•     ECDSA384
•     ECDSA512

    2. Walidacja

Certyfikat ASPSP jest przesyłany w każdej odpowiedzi w nagłówku sygnatury JWS o nazwie „x5c”. Dzięki niemu możesz zweryfikować czy podpis w sygnaturze JWS jest autentyczny, czy został rzeczywiście wygenerowany przez ASPSP do którego wysłałeś zapytanie.

Sposób przesłania certyfikatu jest jedyną różnicą między sygnaturami dla zapytań i odpowiedzi.

Aby upewnić się, czy odpowiedź ASPSP jest autentyczna i niezmieniona, sprawdź czy zgadzają się wartości: kid, skrót certyfikatu oraz podpis w sygnaturze JWS.

  3. Nagłówek Authorization

W celu wykonywania operacji z użyciem API będziesz potrzebował zgody udzielonej przez PSU. Informacja o tej zgodzie jest reprezentowana jako token dostępu i przesyłana w nagłówku HTTP Authorization oraz dodatkowo w treści zapytania w polu requestHeader/token.

Przesłanie tokena dostępu jest wymagane w większości metod PolishAPI. Wyjątkami są:

•     Metody usługi AS (/authorize, /token)
•     Metoda /deleteConsent służąca do usunięcia zgody,
•     Metoda /getConfirmationOfFunds służąca do pobrania informacji o dostępnych środkach na rachunku PSU.

  4. Opis procesu OAuth2

Udzielenie zgody za pomocą protokołu OAuth2 odbywa się poprzez wykorzystanie usługi AS PolishAPI.

• Pierwszym krokiem ubiegania się o zgodę jest wysłanie zapytania za pomocą metody /authorize, w której wskażesz, do jakich operacji chcesz otrzymać zgodę. Po pozytywnej weryfikacji zapytania otrzymasz w odpowiedzi adres, pod którym jest wystawiony serwis bankowości internetowej, w której PSU udziela zgody.
• Przekieruj PSU na otrzymany adres. PSU powinien zalogować za pomocą poświadczeń wykorzystywanych w Banku.
• PSU w niektórych przypadkach będzie miał możliwość wskazać w bankowości internetowej co będzie wchodziło w skład zgody. O wyborze PSU i ewentualnych zmianach zakresu zgody dowiesz się dopiero przy przesyłaniu kolejnych żądań do Banku.
• Udzielenie zgody przez PSU (obejmujące również SCA) kończy się przekierowaniem PSU do TPP na adres wskazany w parametrze redirect_uri zapytania /authorize. Jest tam przesyłany parametr auth_code.
• Mając auth_code możesz wywołać metodę /token w celu ustanowienia sesji komunikacyjnej z Bankiem i uzyskania tokenów. W body żądania przekaż otrzymany wcześniej wartości auth_code w atrybucie „Code”. Otrzymasz odpowiedź zawierającą:
  • access_token – token dostępu do wszystkich metod wymagających autoryzacji, którego możesz użyć do wywołania metod AIS i PIS zgodnie z zakresem udzielonej zgody.
  • refresh_token – token służący do odnowienia tokena dostępu bez konieczności ponownej autoryzacji (refresh_token posiada datę ważności).

Szczegółowy przebieg i znaczenie poszczególnych etapów tego procesu są opisane w dokumentacji PolishAPI.

5. Reguły obsługi zgód

Specyfikacja PolishAPI zostawia pewną dowolność w implementacji niektórych mechanizmów. W naszym API zostały wprowadzone następujące reguły dotyczące zgód i sesji:

• W polu scopeGroupType można wysłać tylko jedną wartość spośród dostępnych (ais-accounts, ais bądź pis), a nie listę.
• Elementy przesyłane w liście privilegeList zależą od wartości w scopeGroupType:
  • ais-accounts -> możliwy jest tylko jeden element listy z wypełnionym polem ais-accounts:getAccounts. Numer konta powinien zostać pusty (jest ignorowany);
  • ais -> możliwa jest lista elementów, ale tylko dla zapytań o różne konta tj. każdy element listy ScopeDetailsPrivilegeList powinien odnosić się do innego numeru konta. Każdy z elementów listy może mieć wypełnione dowolne uprawnienia zgodne z typem zgody ais. Jeśli chcesz zapytać o szczegóły dowolnego konta (numer konta uzupełniony będzie przez PSU w trakcie udzielania zgody w Banku) to wtedy lista privilegeList zawiera dokładnie jeden element, który nie zawiera numeru konta;
  • pis -> dozwolony jest tylko jeden element w liście privilegeList i musi dotyczyć zgody typu pis. Numer konta powinien zostać pusty (jest ignorowany). W przypadku braku uzupełnienia numeru konta nadawcy przelewu w polu sender, konto jest wybierane przez PSU podczas udzielania zgody w Banku.
• Interpretacja sesji:
  Zgodnie z dokumentacją PolishAPI, sesja XS2A rozpoczyna się w momencie przyznania zgody i zwrócenia access_token (metoda /token). Czas ważności sesji XS2A jest definiowany w metodzie /authorize przez parametr scopeTimeLimit, natomiast czas ważności sesji w sensie technicznym jest ustalony przez czas życia access_token i jest czasem wielokrotnie krótszym od czasu ważności sesji XS2A. Gdy czas ważności access_token minie, sesję techniczną można nawiązać za pomocą operacji odświeżenia tokena (użycie refresh_token w metodzie /token), wtedy zostanie zwrócony nowy access_token.
• Odświeżanie zgody dla mniejszego bądź równego zakresu:
  Zgodę można odświeżyć przy użyciu refresh_token tylko dla takiego samego zakresu, a nie mniejszego. W przypadku niektórych zgód PIS dodatkowo możliwa jest operacja refresh_token zmieniająca scope na getPayment (zgodnie z PolishAPI).
  • Dla pis:
    • Brak scope = niezmieniony zakres
    • pis:getPayment = zmiana na token do pobierania statusu transakcji (getPayment). Możliwe tylko jeśli oryginalna zgoda była na domestic, tax, EEA lub nonEEA.
    • Inne scope (w szczególności taki sam, jak oryginalny) = błąd
  • Dla ais i ais-accounts:
    • Brak scope = niezmieniony zakres
    • Inne scope (w szczególności taki sam, jak oryginalny) = błąd.
• Możliwe jest wygenerowanie nowego access_token w oparciu o refresh_token bądź exchange_token, nawet dla przekroczenia limitu użycia uprawnienia. Dopiero użycie któregoś z tych tokenów w konkretnej metodzie zwróci błąd.
• Możliwe jest odpytanie podczas jednej sesji dowolną ilość razy operacji stronicowanych/filtrowanych i są one traktowane jako pojedyncze zapytanie (w ramach trwania sesji). Innymi słowy licznik zostanie zwiększony co najwyżej jednokrotnie dla danego access_tokena. W przypadku braku użycia metody, licznik oczywiście nie zostanie w ogóle zwiększony.
• Limit zgód w usługach PIS:

Pomimo tego, że parametr scopeUsageLimit jest dostępny również w usługach PIS, nie są możliwe dowolne wartości w usługach PIS. Wartość Multiple jest możliwa tylko dla usług getPayment, getBundle oraz getReccurringPayment, które są operacjami odczytu.

6. Środowisko Sandbox

Środowisko Sandbox służy do testowania prawidłowości Twojej implementacji komunikacji z naszym API. Za pomocą API wystawionego na tym środowisku możesz otrzymać rzeczywiste odpowiedzi na usługi API. Środowisko Sandbox zawiera również serwis bankowości internetowej, dzięki czemu możesz sprawdzić co zobaczy PSU w systemie banku i przetestować różne scenariusze jego zachowań.

Aby skorzystać z funkcjonalności środowiska Sandbox musisz z Portalu Developera pobrać dane testowe PSU. Powinieneś także wygenerować sobie certyfikaty testowe wymagane do komunikacji PolishAPI lub ewentualnie możesz skorzystać z certyfikatu produkcyjnego, jeśli taki posiadasz.

  1. Cechy i ograniczenia

Środowisko Sandbox stara się jak najbardziej wiernie odwzorować środowisko produkcyjne, ale pewnych różnic nie sposób uniknąć.

Korzystając ze środowiska Sandbox pamiętaj, że:

• Ze środowiskiem Sandbox możesz komunikować się za pomocą certyfikatów testowych wygenerowanych w Portalu Developera lub produkcyjnych. Certyfikaty testowe są identyczne jak produkcyjne, tylko wydane przez inne CA.
• Na środowisku Sandbox jest udostępniona bankowość internetowa. Używasz jej w celu udzielenia zgody zgodnie z wymaganiami PolishAPI. Logowanie do niej odbywa się za pomocą loginu i hasła dostępnych w danych testowych.
• Na środowisku Sandbox zgody działają zgodnie z PolishAPI, z uwzględnieniem różnic w implementacji PolishAPI przez Bank, opisanych wcześniej w tym dokumencie.
• Wynik transakcji (czy uda się czy nie i po jakim czasie) zależy od wybranego rachunku. Status transakcji może zmieniać się w czasie, w zależności od rachunku. Zachowanie poszczególnych rachunków możesz sprawdzić w opisie danych testowych.
• Na środowisku Sandbox można zlecać płatności z datą przyszłą. Takie transakcje będą wykonane (zmieni im się odpowiednio status) po osiągnięciu dnia podanego w executionDate o stałej godzinie wybranej przez Bank.
• Środowiska Sandbox dotyczą również podobne ograniczenia na liczbę zapytań, jak na środowisku produkcyjnym, przy czym wartości limitów na środowisku Sandbox mogą być inne.
• Nie używaj środowiska Sandbox do testów wydajnościowych lub obciążeniowych.
• Środowisko Sandbox ma inne adresy niż środowisko produkcyjne.

Na środowisku Sandbox niektóre operacje przebiegają nieco inaczej niż na środowisku produkcyjnym:

• Na środowisku Sandbox nie odbywa się proces księgowania transakcji, w związku z czym:
  • Transakcje wykonane usługą PIS nie są widoczne w usłudze AIS. Dotyczy to także płatności cyklicznych (recurring payments), których nie będzie widać w historii rachunku.
  • Salda rachunków nie są aktualizowane po transakcjach wykonanych usługą PIS.
• Do zatwierdzenia zgody w bankowości internetowej jest potrzebny kod OTP. Na środowisku Sandbox SMS-y nie są wysyłane, jako OTP możesz podać dowolny ciąg 6 znaków.
• Nie są obsługiwane transakcje mass payment, w związku z tym w odpowiedzi na /getTransactionDetail numer wirtualny (accountMassPayment) będzie zawsze pusty.
• Dla każdego rachunku można wywołać /getConfirmationOfFunds i nie zakończy się ono błędem z powodu braku zgody klienta. Sprawdzenie dostępności środków odbywa się na podstawie salda rachunku.

  2. Generacja certyfikatu testowego

Generowanie certyfikatu jest dostępne po zalogowaniu do Portalu Developera w zakładce "Certyfikaty". Aby wygenerować certyfikat kliknij przycisk "Generuj certyfikat". Po jego wygenerowaniu zostanie wyświetlony klucz prywatny. Klucz prywatny jest wspólny dla obu certyfikatów. Koniecznie go zachowaj, ponieważ ze względów bezpieczeństwa jest on prezentowany wyłącznie podczas generowania i nie jest zapamiętywany. Same certyfikaty możesz pobrać w dowolnym momencie.

Jeśli utracisz klucz prywatny możesz ponownie wygenerować certyfikat testowy. W tym momencie stary certyfikat przestanie działać.

Certyfikat testowy QSeaC musisz wystawić tak, aby miał adres, który pozwoli wypełnić nagłówek x5u i był możliwy do pobrania przez nas w trakcie walidacji sygnatury JWS.

  3. Dane testowe

W celu przeprowadzenia testów dla developerów została przygotowana zakładka zawierająca dane testowe. Można je znaleźć, po zalogowaniu się do Portalu Developera, w zakładce "API" a następnie "Dane testowe".

Dane testowe do środowiska Sandbox zawierają następujące informacje:

• Login i hasło potrzebne do zalogowania użytkownika do testowej bankowości internetowej
• Typ konta - rodzaj rachunku bankowego (konto osobiste lub korporacyjne)
• Numer konta bankowego składający się z 26 cyfr
• Waluta w jakiej jest prowadzony rachunek bankowy, niektóre mogą być w walucie innej niż PLN
• Opis konta – cechy danego rachunku i/lub klienta, może też zawierać informacje o szczególnym zachowaniu tego rachunku, jeśli jest nietypowe.

  4. Certyfikaty QWAC w początkowym okresie funkcjonowania API

W początkowym okresie funkcjonowania API dla środowiska Sandbox może okazać się, że certyfikat QWAC ze strony Banku ma charakter testowy i nie jest w pełni poprawnym certyfikatem kwalifikowanym. W takim przypadku udane zestawienie połączenia w ramach protokołu HTTPS będzie od Ciebie wymagało wyłączenia mechanizmu weryfikacji hosta (hostname verification) oraz ewentualnie dodatkowych mechanizmów walidacji certyfikatu QWAC, jakie możesz mieć po swojej stronie zaimplementowane. Ze względu na dowolność technologii, której możesz używać do łączenia się z API nie jest możliwe opisanie tutaj dokładnego sposobu realizacji tego dodatkowego wymagania.

Opisana sytuacja (o ile w ogóle wystąpi) będzie miała charakter przejściowy i nigdy nie będzie dotyczyła komunikacji produkcyjnej.

7. Środowisko produkcyjne

  1. Certyfikaty produkcyjne

Aby łączyć się ze środowiskiem produkcyjnym potrzebujesz produkcyjnych certyfikatów QWAC i QSealC wystawiony przez odpowiednie centrum autoryzacji.

Zgodnie z PSD2 właściwa instytucja - NCA (ang. National Competent Authority) jest odpowiedzialna za nadzór nad dostawcami usług płatniczych (ASPSP, TPP) w swoich krajach. W Polsce jest to KNF. W przypadku przyznania autoryzacji, NCA nadaje numer autoryzacyjny oraz publikuje dane w krajowych rejestrach.

Lista NCA uprawionych do nadawania uprawnień w komunikacji PSD2 jest dostępna pod adresem: https://www.eba.europa.eu/supervisory-convergence/supervisory-disclosure/competent-authorities.
TSP (ang. Trust Service Provider) jest podmiotem odpowiedzialnym za fizyczne wydanie certyfikatu zgodnego z PSD2. Jest to podmiot świadczący usługi w zakresie kwalifikowanych certyfikatów eIDAS. Należy zwrócić się do takiego podmiotu w celu uzyskania certyfikatu.

  2. Ograniczenia

Aby zapewnić bezproblemowe działanie systemów wprowadziliśmy następujące ograniczenia:

• Limit liczby zapytań od jednego TPP w czasie chroni API przed atakami typu DoS (Denial of Service). Jeżeli przekroczysz limit, otrzymasz w odpowiedzi kod 429 (Too many requests), a zapytanie nie zostanie przetworzone. Po otrzymaniu takiej odpowiedzi odczekaj chwilę zanim zaczniesz wysyłać kolejne zapytania.
• Ograniczona jest również częstotliwość odpytywania o stan pojedynczej lub paczki transakcji (metody /getPayment, /getBundle oraz /getRecurringPayment). O stan danej transakcji lub paczki możesz pytać nie częściej, niż raz na minutę. O przekroczeniu limitu zostaniesz poinformowany kodem 429 (Too many requests).