Bramka płatnicza Dokumentacja techniczna wersja 1.0
strona 2 z 15 Spis treści 1. Wstęp... 3 2. Słownik pojęć... 3 3. Usługa bramki płatniczej... 4 3.1 Realizacja płatności... 4 3.1.1 Postępowanie... 4 3.2 Bezpieczeństwo... 5 3.3 Wdrażanie po stronie sprzedawcy... 5 3.3.1 Przesłanie zlecenia za pośrednictwem formularza HTML... 6 3.3.2 Przesłanie zlecenia poprzez stworzenie URL... 6 3.3.3 Wyliczenie kodu uwierzytelniającego HMAC... 7 3.3.4 Weryfikacja podpisu cyfrowego ECDSA... 8 3.4 Płatność przez bramkę płatniczą... 9 3.4.1 Identyfikacja płatności... 9 3.4.2 Zlecenie... 9 3.4.3 Odpowiedź na zlecenie... 11 3.4.5 Zwrotny URL i parametry... 12 3.4.6 Notyfikacyjny email... 13 4. Przykłady... 14 4.1 PHP...14 4.2 Java...14
strona 3 z 15 1. Wstęp Niniejszy dokument opisuje wdrożenie usługi bramki płatniczej. Celem dokumentu jest udzielenie instrukcji w jaki sposób stworzyć prawidłowo działające i bezpieczne połączenie pomiędzy serwerem bankowości internetowej instytucji płatniczej Payment a serwerem Sprzedawcy i opisać przebieg komunikacji pomiędzy nimi. Dokument przeznaczony jest dla osób posiadających wiedzę techniczną. 2. Słownik pojęć Bramka płatnicza usługa, która umożliwia klientom, którzy posiadają upoważnienie do dysponowania rachunkiem bieżącym, realizować płatności online na konto Sprzedawcy. HMAC kod autoryzacyjny, który wyliczony jest z łańcucha (skonstruowanego według specyfikacji) i klucza bezpieczeństwa, który otrzyma sprzedawca od instytucji płatniczej. Służy do weryfikacji integralność wiadomości przesyłanych pomiędzy serwerem instytucji płatniczej a serwerem sprzedawcy. ECDSA podpis cyfrowy stworzony przez algorytm ECDSA, który wysyłany jest w odpowiedziach z serwera instytucji płatniczej i służy do weryfikacji autentyczności. Sprzedawca sprawdzi podpis za pomocą klucza publicznego. Klucz bezpieczeństwa klucz składający się z 128 znaków, który jest Sprzedawcy przekazany przy podpisaniu umowy. Klucz publiczny klucz służący do kontroli podpisu ECDSA.
strona 4 z 15 3. Usługa bramki płatniczej Usługa bramki płatniczej umożliwia klientom, którzy mają upoważnienie do dysponowania rachunkiem bieżącym, realizować płatności online na konto sprzedawcy za pośrednictwem specjalnego odsyłacza URL, który może zostać umieszczony na stronie internetowej (sklepie internetowym). 3.1 Realizacja płatności Podstawowym zadaniem usługi jest płatność za towar lub usługi w sklepach internetowych. 3.1.1 Postępowanie 1. klient po zakupie towaru lub usług w sklepie internetowym kliknie na symbol płatności za pośrednictwem bramki płatniczej. 2. serwer sprzedawcy przekieruje klienta za pośrednictwem odsyłacza URL na serwer bankowości internetowej instytucji płatniczej. 3. instytucja płatnicza sprawdzi ważność i prawidłowość parametrów przesyłanych za pośrednictwem URL i wyświetli aplikację bramki płatniczej. 4. klient zaloguje się za pomocą danych identyfikacyjnych (e-mail, hasło i kod z urządzenia autoryzacyjnego). 5. aplikacja wyświetli wstępnie wypełniony formularz płatności z rachunku bieżącego klienta na konto sprzedawcy. Klient może zmienić konto płatnika w przypadku, że ma upoważnienie do wykonywania płatności na kilku rachunkach bieżących. 6. klient potwierdzi lub anuluje płatność. 7. aplikacja wyświetli klientowi informację o wyniku przetwarzania płatności. 8. klient wciśnie przycisk Kontynuować, aby powrócić do strony sprzedawcy. 9. Sprzedawca sprawdzi wynik przetwarzania płatności. Do dyspozycji ma następujące możliwości: kontrola parametrów w zwrotnym URL kontrola emailu powiadamiającego (jeżeli został prawidłowo wypełniony parametr remail w zleceniu) kontrola operacji na koncie za pośrednictwem bankowości internetowej lub aplikacji mobilnej
strana 5 z 15 3.2 Bezpieczeństwo Komunikacja pomiędzy sprzedawcą a instytucją płatniczą jest: przenoszona i szyfrowana protokołem SSL serwer sprzedawcy i instytucji płatniczej zabezpieczy integralność przesyłanych danych za pośrednictwem kodu autoryzacyjnego (HMAC), który obliczony jest z parametrów i klucza bezpieczeństwa, który otrzyma sprzedawca od instytucji płatniczej serwer instytucji płatniczej dodatkowo podpisze odpowiedzi podpisem cyfrowym (ECDSA), który sprzedawca sprawdzi na podstawie klucza publicznego Sprzedawca zobowiązany jest sprawdzić autentyczność odpowiedzi z banku poprzez weryfikację prawdziwości kodu uwierzytelniającego HMAC i podpisu cyfrowego ECDSA. Jeżeli HMAC i ECDSA nie zgadzają się z wyliczonymi wartościami po stronie Sprzedawcy, odpowiedź jest oceniona jako podejrzana i Sprzedawca zobowiązany jest skontaktować się z instytucją płatniczą w celu weryfikacji wyniku przetwarzania płatności lub innej odpowiedzi. 3.3 Wdrożenie po stronie sprzedawcy Wymogi dotyczące wdrożenia: przekierowanie na serwer bankowości internetowej nie jest możliwe przez iframe. sprzedawca może przesyłać zlecenia na poniżej podane URL usługi bramki płatniczej metodą GET lub POST przez protokół HTTPS parametry zostaną zakodowane w formie application/x-www-form-urlencoded każde zlecenie musi zawierać kod uwierzytelniający HMAC odpowiedzi serwera instytucji płatniczej zawierają kod uwierzytelniający HMAC i podpis cyfrowy ECDSA, które Sprzedawca zobowiązany jest zweryfikować sprzedawca przy podpisaniu umowy otrzyma od instytucji płatniczej swój identyfikator vt i klucz bezpieczeństwa.
strona 6 z 15 3.3.1 Przesłanie zlecenia za pośrednictwem formularza HTML Serwer sprzedawcy wygeneruje stronę ze ukrytym formularzem, który zawiera input pola typu hidden dla każdego parametru wyjściowego. Dla formularza zaleca się nastawić parametr method na wartość POST. W przypadku, że nie obsługuje jej dany serwer sieciowy, można zastosować wartość GET. Przykład: 3.3.2 Przesłanie zlecenia poprzez stworzenie URL Serwer Sprzedawcy wygeneruje odsyłacz URL, który składa się z URL dla wybranego interfejsu i parametrów wejściowych: [URL dla wybranego interfejsu]?[łańcuch parametrów wejściowych] Ogólna URL dla wybranego interfejsu jest w formie: https://subdomena.pay-institution.eu/gateway/ napr.: https://ib.pay-institution.eu/gateway/ Dla łańcucha parametrów wyjściowych obowiązują: wartości parametrów kodowane są metodą standardową URLEncode nazwy parametrów są oddzielone od wartości znakiem = (np. vt=1) parametry oddzielone są znakiem & (np vt =1&amount=123.45) Przykład przesłanego zlecenia:
strana 7 z 15 3.3.3 Wyliczenie kodu uwierzytelniającego HMAC Serwer Sprzedawcy musi: wyliczyć kod uwierzytelniający HMAC i dodać go do parametrów zapytania przesłanego na serwer instytucji płatniczej wyliczyć kod uwierzytelniający HMAC i zweryfikować wyliczoną wartość w stosunku do parametru HMAC w odpowiedzi z serwera instytucji płatniczej. W przypadku, że wartości nie zgadzają się, musi odpowiedz ocenić jako nieważną i skontaktować się z instytucją płatniczą w celu weryfikacji płatności. Metody obliczenia: 1. serwer Sprzedawcy przygotuje łańcuch, który jest wejściem do wyliczenia kodu uwierzytelniającego HMAC (według opisu w podrozdziałach poniżej) 2. z tego łańcucha wygeneruje mieszany kod uwierzytelniający(hmac) z wykorzystaniem: funkcji kryptograficznej SHA-256 64 bajtowego klucza bezpieczeństwa, który zapisany jest w systemie szesnastkowym (128 znaków)
strona 8 z 15 3.3.4 Weryfikacja podpisu cyfrowego ECDSA Serwer sprzedawcy sprawdzi podpis cyfrowy ECDSA, który znajduje się w odpowiedziach z serwera instytucji płatniczej. W przypadku, że weryfikacja nie powiodła się, oceni odpowiedź jako nieważną. Serwer sprzedawcy sprawdzi ten podpis cyfrowy w następujący sposób: Sprzedawca pobierze klucze publiczne z serwera instytucji płatniczej w formie pliku i zapisze go na serwer. Uwaga: Instytucja płatnicza w razie konieczności może zmienić klucz publiczny. Ogólny adres URL, na którym dostępny jest klucz publiczny: https://subdomena.pay-institution.eu/gateway/ecdsa napr. https://ib.pay-institution.eu/gateway/ecdsa 2. serwer sprzedawcy przygotuje taki sam łańcuch jak w przypadku weryfikacji HMAC i dołączy do niego wartość HMAC (wartość przyjętą lub wyliczoną muszą być zgodne) 3. sprawdzi podpis cyfrowy wywołując funkcję OpenSSL (OpenSSL biblioteki 1.0.0 i wyższe) do weryfikacji podpisu cyfrowego ECDSA, której wejściem jest: łańcuch dla weryfikacji podpisu cyfrowego wybór funkcji kryptograficznej SHA-256 podpis cyfrowy przesłany w odpowiedzi w parametrze ECDSA
strona 9 z 15 3.4 Płatność przez bramkę płatniczą 3.4.1 Identyfikacja płatności Sprzedawca musi zidentyfikować płatność za pomocą jednej z poniższych możliwości: symbol zmienny ew. symbol specyficzny i symbol zmienny referencja płatnika (ten identyfikator płatności został wprowadzony w ramach płatności SEPA) Wybrany identyfikator / identyfikatory: prześle sprzedawca w zleceniu płatności przez bramkę płatniczą prześle instytucja płatnicza sprzedawcy w zwrotnym URL i e-maila powiadamiającego 3.4.2 Zlecenie Serwer handlowca wyśle zlecenie metodą GET lub POST na adres URL: ogólnie: https://subdomena.pay-institution.eu/gateway na przykład: https://ib.pay-institution.eu/gateway Uwaga: Poprzez dodanie języka za koniec URL można dzwonić na bramkę płatniczą w danym języku. Na przykład dla języka czeskiego będzie odnośnik URL w formacie https://subdomena.pay-institution.eu/gateway/cz. Dozwolone są języki cz, pl i en, gdzie domyślnym językiem jest sk.
strana 10 z 15 Parametry wejściowe Nazwa Obowiązk owy Opis vt tak Identyfikator sklepu 1-11 Długo ść Zasady Przykład Udziela instytucja płatnicza 1 Unikatowy numer identyfikacyjny sklepu. amount tak Suma płatności 9+2 - cyfra dziesiętna 123.45 Suma, którą ma klient przelać na konto handlowca. - maks 9 miejsc przed currency tak Waluta płatności 3 przecinkiem dziesiętny ch - maks 2 miejsca po przecinku oddzielone kropką - musi zawierać kod waluty według normy ISO 4217 vs tak Symbol zmienny <10 - dozwolone znaki: 0-9 123456789 ss nie Symbol specyficzny <10 - dozwolone znaki: 0-9 987654321 cs nie Symbol stały <4 - dozwolone znaki: 0-9 308 remail nie Adres e-mail do <50 - może zawierać tylko jeden adres e-mail vysledok@obchod. przesłania powiadomienia ważny zgodnie z sk o wyniku płatności RFC 2822 EUR - w przypadku, że wartość przekroczy 50 znaków, e-mail z powiadomieniem nie zostanie wysłany rurl tak Zwrotna URL - URL musi zostać https://www.obchod URL adres, na który utworzona zgodnie z.sk/vysledok_płatnoś ci bank przekieruje RFC 1738 i musi działać hmac tak klienta po dokonaniu płatności. Kod uwierzytelniający +64 - obowiązujące znaki: 0-9 a- 95d62075f3ce9c53 HMAC z parametrów: f 9b52e1c8fad45c4c vt + amount 15fd38701f1a12ad
currency + vs + ss + e6122bb3ca40ed1 cs + rurl + remail + 6 timestamp timestamp tak Timestamp (znacznik 14 - w formacie 21022018072746 czasu) w UTC DDMMYYYYHHMIS Serwer Instytucji S płatniczej przetworzy tylko zlecenia, które (DD- dzień, będą mieć TIMESTAMP w przedziale MM-miesiąc, YYYY- rok, HH- godzina +/- 1 godzina MI-minuta, w stosunku do UTC (GMT) SS- sekunda) 3.4.3 Odpowiedź na zlecenie W przypadku, gdy zlecenie jest ważny a usługa bramki płatniczej jest dostępna, klientowi wyświetli się aplikacja bramki płatniczej. Za pośrednictwem aplikacji można potwierdzić płatność na konto sprzedawcy. Po potwierdzeniu lub anulowaniu płatności klientowi wyświetli się jedno ze zgłoszeń: Wartość Zgłoszenie result Twoja płatność została pomyślnie zrealizowana OK Popis Twoja płatność nie została zrealizowana. FAIL Wystąpił błąd podczas realizacji. Klientowi wyświetli się także powód błędu np. brak środków na koncie. Płatność została anulowana CANCEL Wyświetli się w przypadku, gdy klient anulował płatność. Sprzedawca może sprawdzić stan płatności w poniższy sposób: kontrola parametrów w zwrotnym URL kontrola e-maila powiadamiającego (jeżeli został prawidłowo wypełniony parametr remail w zleceniu) popyt online na serwer instytucji płatniczej kontrola operacji na koncie za pośrednictwem bankowości internetowej lub aplikacji mobilnej
strona 12 z 15 3.4.5 Zwrotny URL i parametry Aplikacja bramki płatniczej wyświetli klientowi wynik płatności. W przypadku, gdy klient nie zamknie okna wyszukiwarki, ale wciśnie przycisk Kontynuować, zostanie przekierowany na strony URL sprzedawcy (przesłany w parametrze wejściowym rurl). Zwrotny URL zawiera parametry, dzięki którym może serwer sprzedawcy sprawdzić stan płatności. Nazwa Popis Przykład amount currency vs ss cs result pid Suma płatności przesłana w zleceniu Waluta płatności przesłana w zleceniu Symbol zmienny (Identyfikator) Symbol specyficzny Symbol stały Kod wyniku płatności: OK - płatność została pomyślnie zrealizowana FAIL - płatność nie została pomyślnie zrealizowana CANCEL - klient anulował płatność Jednoznaczny identyfikator płatności po stronie instytucji płatniczej timestamp hmac ecdsa Za pomocą tego identyfikatora można w prosty sposób powtórnie sprawdzić stan płatności za pośrednictwem Interfejsu. Parametr znajduje się w odpowiedzi, jeżeli wynik płatności je OK. Timestamp przesłany w zleceniu Łańcuchem do wyliczenia HMAC jest łańcuch wartości parametrów: amount + currency + vs + ss + cs + result + pid + timestamp Łańcuchem do wyliczenia ECDSA jest łańcuch wartości parametrów: amount + currency + vs + ss + cs + result + pid + timestamp + hmac
strana 13 z 15 3.4.6 Powiadomienia e-mail Serwer instytucji płatniczej wyśle powiadomienie e-mailem na adres podany w parametrze remail. Email zawiera łańcuch parametrów, takich samych jak zwrotny URL: nazwy parametrów są oddzielone od wartości znakiem = parametry są wzajemnie oddzielone spacją jeżeli parametr nie jest wypełniony, nie będzie znajdować się w łańcuchu (ani nazwa ani wartość) parametry zostaną uszeregowane w poniższej kolejności: 1. amount 2. currency 3. vs 4. ss 5. cs 6. result 7. pid 8. timestamp 9. hmac 10. ecdsa
strana 14 z 15 4. Przykłady W celu kontroli generowania HMAC instytucja płatnicza oferuje możliwość sprawdzenia prawidłowego generowania HMAC przez adres URL: (ogólnie) https://subdomena.pay-institution.eu/gateway/example Dla konkretnej poddomeny jest to adres URL: https://ib.pay-institution.eu/gateway/example 4.1 PHP Wyliczenie HMAC Wyliczenie ECDSA 4.2 JAVA Wyliczenie HMAC Wyliczenie ECDSA