Przelewy24 Płatności Mobilne

Komentarze

Transkrypt

Przelewy24 Płatności Mobilne
Płatności mobilne Przelewy24 – Specyfikacja techniczna
Opracował: Arkadiusz Macudziński
(Telefon 61 642 93 43)
Płatności mobilne Przelewy24
Specyfikacja techniczna
Data: 2016-02-05 Wersja: 2.0.8
Dokument zawiera opis rozwiązań płatności Przelewy24 możliwych do implementacji w
aplikacjach mobilnych. Opisane zostały sposoby realizacji płatności, warianty konfiguracyjne,
oraz szczegółowa instrukcja implementacji w aplikacji mobilnej.
Ogólne przykłady konfiguracji bibliotek mobilnych podane są w języku Java (Android). W
kolejnych sekcjach dokumentu można znaleźć szczegółowe przykłady dla każdej platformy.
W wielu miejscach niniejsza dokumentacja odnosi się do dokumentacji płatności www.
Dokument
ten
można
pobrać
pod
adresem
http://www.przelewy24.pl/files/cms/2/przelewy24_specyfikacja_3_2.pdf.
Dokumentacja odnosi się do bibliotek mobilnych w wersjach: Android v. 2.0.6, iOS v. 2.0.4,
Windows Phone Silverlight v. 2.0.2 i Windows Phone Runtime v. 2.0.3.
UWAGA! Aby otrzymywać powiadomienia o aktualizacjach bibliotek mobilnych, należy wysłać na adres [email protected]
wiadomość o treści "Proszę o dopisanie adresu (tu podać e-mail) do listy mailingowej informującej o aktualizacjach bibliotek
mobilnych.", podając swój e-mail kontaktowy. Na podany adres będą przesyłane wyłącznie informacje o aktualizacjach bibliotek, nie
będzie on wykorzystywany do wysyłania żadnych informacji marketingowych.
DialCom24 Sp. z o.o. Ul. Kanclerska 15, 60-327 Poznań, Polska
tel. +48 48 61 642 93 44 fax + 48 61 642 90 31 [email protected]
NIP 781-173-38-52, REGON 634509164, Sąd Rejonowy Poznań, VIII Wydz. Gospodarczy Krajowego Rejestru Sądowego
Nr KRS 0000306513, wysokość kapitału zakładowego: 1 697 000 zł
Strona 1 z 29
Płatności mobilne Przelewy24 – Specyfikacja techniczna
Opracował: Arkadiusz Macudziński
(Telefon 61 642 93 43)
Spis treści
1 Natywne biblioteki mobilne (Android, iOS i Windows Phone SDK)...............................................4
1.1 Opis zastosowania.............................................................................................................................4
1.2 Jak wygląda przebieg transakcji przy użyciu biblioteki mobilnej?..............................................4
1.3 Jak zaimplementować w aplikacji płatność „one click” kartą?................................................5
1.4 Jak zainicjować płatność biblioteką mobilną?.............................................................................7
1.4.1 Wejście bezpośrednio z danymi transakcji..................................................................................7
1.4.2 Wejście z tokenem transakcji.........................................................................................................7
1.5 Jak uruchomić transakcję z konkretną metodą płatność?.........................................................8
1.6 Jak ustawić konkretny kanał płatności?.........................................................................................8
1.7 Jak uruchomić tryb testowy?............................................................................................................8
1.8 Jak zweryfikować poprawność transakcji?....................................................................................9
1.8.1 Weryfikacja za pośrednictwem serwera partnera.....................................................................9
1.8.2 Weryfikacja wewnątrz systemu Przelewy24.................................................................................9
1.9 Jak włączyć responsywne strony banków?.................................................................................10
1.10 Jak włączyć zapamiętywanie haseł do banków?...................................................................10
1.11 Jak ustawić domyślnie zapamiętywanie haseł do banków?..................................................10
1.12 Jak włączyć automatyczne kopiowanie haseł SMS?..............................................................10
1.13 Jak automatycznie powrócić do aplikacji w momencie zakończenia transakcji?.............11
1.14 Jak ograniczyć klientowi czas dostępny na zrealizowanie płatności?..................................11
1.15 Jak anulować płatność i wrócić do aplikacji?..........................................................................11
1.16 Jak ustawić styl ActionBar biblioteki dla Androida < 3.0..........................................................11
2 Definicje................................................................................................................................................12
3 Integracja biblioteki Android w projekcie aplikacji.......................................................................12
3.1 Konfiguracja projektu.......................................................................................................................12
3.2 Konfiguracja biblioteki.....................................................................................................................13
3.3 Wywołanie transakcji.......................................................................................................................14
3.4 Obfuskacja projektu aplikacji.........................................................................................................15
DialCom24 Sp. z o.o. Ul. Kanclerska 15, 60-327 Poznań, Polska
tel. +48 48 61 642 93 44 fax + 48 61 642 90 31 [email protected]
NIP 781-173-38-52, REGON 634509164, Sąd Rejonowy Poznań, VIII Wydz. Gospodarczy Krajowego Rejestru Sądowego
Nr KRS 0000306513, wysokość kapitału zakładowego: 1 697 000 zł
Strona 2 z 29
Płatności mobilne Przelewy24 – Specyfikacja techniczna
Opracował: Arkadiusz Macudziński
(Telefon 61 642 93 43)
3.5 Znane błędy......................................................................................................................................16
4 Integracja biblioteki iOS w projekcie aplikacji...............................................................................16
4.1 Konfiguracja projektu.......................................................................................................................16
4.2 Konfiguracja biblioteki.....................................................................................................................18
4.3 Wywołanie transakcji.......................................................................................................................19
5 Integracja biblioteki Windows Phone w projekcie aplikacji.........................................................20
5.1 Konfiguracja projektu.......................................................................................................................20
5.1.1 Windows Phone Silverlight............................................................................................................20
5.1.2 Windows Phone Runtime..............................................................................................................20
5.2 Konfiguracja biblioteki.....................................................................................................................21
5.3 Wywołanie transakcji.......................................................................................................................22
DialCom24 Sp. z o.o. Ul. Kanclerska 15, 60-327 Poznań, Polska
tel. +48 48 61 642 93 44 fax + 48 61 642 90 31 [email protected]
NIP 781-173-38-52, REGON 634509164, Sąd Rejonowy Poznań, VIII Wydz. Gospodarczy Krajowego Rejestru Sądowego
Nr KRS 0000306513, wysokość kapitału zakładowego: 1 697 000 zł
Strona 3 z 29
Płatności mobilne Przelewy24 – Specyfikacja techniczna
Opracował: Arkadiusz Macudziński
(Telefon 61 642 93 43)
1 Natywne biblioteki mobilne (Android, iOS i Windows Phone SDK)
1.1 Opis zastosowania
Natywne biblioteki mobilne Andorid, iOS i Windows Phone umożliwiają wykonanie płatności
wewnątrz aplikacji mobilnej, bez konieczności przełączania użytkownika między aplikacją a
przeglądarką lub inną aplikacją. Cały proces płatności odbywa się w jednym oknie aplikacji.
W bibliotekach dostępne są różne metody płatności: przelewy bankowe (automatyczne –
pay-by-link i półautomatyczne), karty płatnicze, wirtualne portfele (np. PayPal, SkyCash, …) i
inne.
1.2 Jak wygląda przebieg transakcji przy użyciu biblioteki mobilnej?
Po wywołaniu płatności na ekranie smartfonu pojawia się okno płatności zawierające
kontrolkę WebView z załadowanym serwisem transakcyjnym przelewy24.pl. Po wybraniu
metody płatności w tym samym oknie ładuje się strona wybranego banku/metody, gdzie
użytkownik loguje się do swojego konta, albo podaje konieczne dane potrzebne do
płatności (w przypadku płatności kartą i innych metod, np. BLIK). Następnie użytkownik
zatwierdza płatność i zostaje przekierowany na ekran oczekiwania na potwierdzenie
zaksięgowania wpłaty.
Rysunek 1: Przebieg procesu płatności z wykorzystaniem biblioteki mobilnej
Po wykonaniu płatności, system Przelewy24 wysyła na adres „p24_url_status” (serwer
sprzedawcy/aplikacji) potwierdzenie wpłaty. Dla potwierdzenia wiarygodności transakcji w
odpowiedzi na potwierdzenie wpłaty system partnera weryfikuje wynik żądaniem zwrotnym.
DialCom24 Sp. z o.o. Ul. Kanclerska 15, 60-327 Poznań, Polska
tel. +48 48 61 642 93 44 fax + 48 61 642 90 31 [email protected]
NIP 781-173-38-52, REGON 634509164, Sąd Rejonowy Poznań, VIII Wydz. Gospodarczy Krajowego Rejestru Sądowego
Nr KRS 0000306513, wysokość kapitału zakładowego: 1 697 000 zł
Strona 4 z 29
Płatności mobilne Przelewy24 – Specyfikacja techniczna
Opracował: Arkadiusz Macudziński
(Telefon 61 642 93 43)
W momencie gdy system partnera wykona połączenie weryfikacyjne, na ekranie smartfona
pojawia się informacja o poprawnej wpłacie, użytkownik może wrócić do aplikacji ze
statusem poprawnej wpłaty.
Rysunek 2: Proces płatności przelewem w bibliotece mobilnej Android
1.3 Jak zaimplementować w aplikacji płatność „one click” kartą?
Płatność „one click” kartą w aplikacji mobilnej polega na możliwości zapamiętania w
aplikacji kart wykorzystanych przy poprzednich płatnościach. Taką kartę można wyświetlić w
aplikacji jako osobną formę płatności. W momencie wybrania tej karty, aplikacja wywołuje
DialCom24 Sp. z o.o. Ul. Kanclerska 15, 60-327 Poznań, Polska
tel. +48 48 61 642 93 44 fax + 48 61 642 90 31 [email protected]
NIP 781-173-38-52, REGON 634509164, Sąd Rejonowy Poznań, VIII Wydz. Gospodarczy Krajowego Rejestru Sądowego
Nr KRS 0000306513, wysokość kapitału zakładowego: 1 697 000 zł
Strona 5 z 29
Płatności mobilne Przelewy24 – Specyfikacja techniczna
Opracował: Arkadiusz Macudziński
(Telefon 61 642 93 43)
natychmiast żądanie bezpośredniego obciążenia karty daną kwotą i płatność zostaje
zrealizowana w ciągu kilku sekund, bez konieczności ponownego podawania danych karty.
Rysunek 3: Płatność "one click" w
aplikacji Android
Technicznie proces płatności „one-click” wymaga współpracy trzech systemów: aplikacji
mobilnej, serwera partnera, oraz WebService Przelewy24 do rekurencji na kartach.
UWAGA: Do realizacji „one-click” niezbędna jest odpowiednia umowa z operatorem kart
płatniczych – prosimy o kontakt z Działem Handlowym Przelewy24 ([email protected],
+48 61 642 93 45).
Proces „one click” jest podzielony na etapy:
•
Najpierw użytkownik wykonuje płatność kartą w aplikacji za pomocą biblioteki
mobilnej.
•
W momencie, gdy transakcja jest potwierdzana przez system Przelewy24 (komunikat
na p24_url_status), serwer partnera dokonuje weryfikacji.
•
Serwer partnera odpytuje WebService Przelewy24 (metoda GetTransactionReference)
podając ID transakcji otrzymanej w połączeniu weryfikacyjnym, otrzymuje w ten
sposób refId karty, przy pomocy której została wykonana wpłata.
•
Serwer partnera odpytuje
WebService (metoda CheckCard) podając refId, aby
sprawdzić czy dana karta udostępnia płatności rekurencyjne.
•
Jeżeli karta udostępnia rekurencję, to serwer partnera zapisuje w bazie danych refId
karty i przypisuje ją do konta użytkownika, który wykonał płatność.
•
Przy kolejnej płatności w aplikacji mobilnej, aplikacja pobiera z serwera listę
zapamiętanych dla danego użytkownika kart i prezentuje ją jako metoda płatności
obok płatności przelewem i dowolną kartą ( Rysunek).
DialCom24 Sp. z o.o. Ul. Kanclerska 15, 60-327 Poznań, Polska
tel. +48 48 61 642 93 44 fax + 48 61 642 90 31 [email protected]
NIP 781-173-38-52, REGON 634509164, Sąd Rejonowy Poznań, VIII Wydz. Gospodarczy Krajowego Rejestru Sądowego
Nr KRS 0000306513, wysokość kapitału zakładowego: 1 697 000 zł
Strona 6 z 29
Płatności mobilne Przelewy24 – Specyfikacja techniczna
•
Opracował: Arkadiusz Macudziński
(Telefon 61 642 93 43)
Użytkownik wybiera kartę z listy, aplikacja łączy się z serwerem partnera, serwer
partnera wywołuje WebService P24 (metoda ChargeCard), system P24 dokonuje
obciążenia karty i zwraca status (ok/error).
Aby zaimplementować płatność „one click” w aplikacji, konieczne jest zaimplementowanie
komunikacji pomiędzy serwerem partnera, a WS Przelewy24 i aplikacją mobilną partnera.
1.4 Jak zainicjować płatność biblioteką mobilną?
Aby zainicjować płatność należy odpowiednio skonfigurować obiekty klas P24Config,
P24Payment i P24. Biblioteka umożliwia zainicjowanie transakcji na dwa sposoby: podając
dane transakcji bezpośrednio w bibliotece, oraz rejestrując wcześniej transakcję i przekazując
do biblioteki tylko token transakcji.
Przykładowe kody implementujące konfigurację biblioteki można znaleźć w rozdziałach 3, 4 i
5.
1.4.1 Wejście bezpośrednio z danymi transakcji
Aby zainicjować transakcję bezpośrednio parametrami płatności, należy utworzyć obiekt
konfiguracyjny (P24Config) i podać w nim id partnera i kod CRC (dostępny w panelu
partnera). Następnie należy utworzyć obiekt P24Payment i podać w nim dane o transakcji:
kwotę (wyrażoną w groszach), walutę (np. „PLN”), e-mail klienta, oraz id sesji (unikalne dla
każdej transakcji). Dodatkowo w obiekcie P24Payment można podać dane adresowe klienta
(nazwisko, adres, miasto, kod pocztowy, kraj), które są wymagane dla płatności kartą, oraz
opis transakcji, który będzie wyświetlany w panelu transakcyjnym Przelewy24.
W zależności od konfiguracji trybu weryfikacji transakcji, należy w obiekcie P24Payment
podać adres p24_url_status. Tryby weryfikacji transakcji są opisane w punkcie 1.8.
Następnie należy wywołać okno płatności. Sposób wywołania okna płatności na każdej
platformie opisany jest w punktach 3.3, 4.3 i 5.3.
1.4.2 Wejście z tokenem transakcji
Możliwe jest zarejestrowanie transakcji za pomocą osobnego zapytania z serwera partnera.
Opis rejestracji transakcji znajduje się w punkcie 5.1 dokumentacji płatności www. Przy
rejestracji transakcji, jeżeli ma być ona wykonana w bibliotece mobilnej, należy dodać
parametr „p24_mobile_lib=1”.
W wyniku rejestracji transakcji otrzymujemy TOKEN. Aby skonfigurować bibliotekę na wejście z
tokenem nie należy ustawiać żadnych danych w obiektach P24Config i P24Payment, tylko w
obiekcie P24Payment podać TOKEN transakcji.
Sposób ustawienia tokenu na każdej platformie opisany jest w punktach 3.2, 4.2 i 5.2.
UWAGA – rejestrując transakcję, która będzie wykonana w bibliotece mobilnej należy
pamiętać o dodatkowych parametrach:
•
p24_channel – jeżeli nie będzie ustawiony, to domyślnie w bibliotece pojawią się
formy płatności „przelew tradycyjny” i „użyj przedpłatę”, które są niepotrzebne przy
DialCom24 Sp. z o.o. Ul. Kanclerska 15, 60-327 Poznań, Polska
tel. +48 48 61 642 93 44 fax + 48 61 642 90 31 [email protected]
NIP 781-173-38-52, REGON 634509164, Sąd Rejonowy Poznań, VIII Wydz. Gospodarczy Krajowego Rejestru Sądowego
Nr KRS 0000306513, wysokość kapitału zakładowego: 1 697 000 zł
Strona 7 z 29
Płatności mobilne Przelewy24 – Specyfikacja techniczna
Opracował: Arkadiusz Macudziński
(Telefon 61 642 93 43)
płatności mobilnej. Aby wyłączyć te opcje należy ustawić w tym parametrze flagi nie
uwzględniające tych form (np. wartość 3 – przelewy i karty, domyślnie ustawione w
bibliotece przy wejściu bezpośrednio z parametrami),
•
p24_method – jeżeli w bibliotece dla danej transakcji ma być ustawiona domyślnie
dana metoda płatności, należy ustawić ją w tym parametrze przy rejestracji, oraz w
bibliotece (P24Payment.setMethod).
1.5 Jak uruchomić transakcję z konkretną metodą płatność?
Aby biblioteka wybrała automatycznie konkretną metodę płatności, należy podać id formy
płatności w parametrze „method”. Można w ten sposób wyciągnąć wybór form płatności do
aplikacji, jeszcze przed wejściem do biblioteki (tak jak np. na rys. Rysunek).
p24payment.setMethod("XXX");
W przypadku konfiguracji z użyciem tokena (pkt. 1.4.2), metodę płatności należy podać
również podczas rejestracji transakcji (parametr p24_method).
Jeżeli ustawiona metoda płatności w danym momencie jest nieaktywna, to zostanie
wyświetlona pełna lista form płatności.
1.6 Jak ustawić konkretny kanał płatności?
Jest możliwość ustawienia w bibliotece konkretnych kanałów płatności, jak np. płatność tylko
kartą, płatność tylko przelewem. W tym celu należy ustawić flagę kanału w parametrze
p24Channel.
p24config.setP24Channel(P24Config.P24_CHANNEL_TRANSFERS);
Szczegółowy opis ustawienia kanałów płatności znajduje się w punkcie 5.1 dokumentacji
płatności
www
(parametr
p24_channel).
Domyślna
wartość
to
„P24Config.P24_CHANNEL_CARDS | P24Config.P24_CHANNEL_24_7”
1.7 Jak uruchomić tryb testowy?
W trybie testowym możliwe jest zweryfikowanie poprawnej implementacji biblioteki i procesu
weryfikacji transakcji, bez konieczności wykonywania przelewu. Po wybraniu dowolnej formy z
listy system pominie proces logowania do banku i wyświetli transakcję jako zaksięgowaną
poprawnie.
Aby testować bibliotekę na środowisku SANDBOX, należy ustawić tryb testowy w obiekcie
P24Config.
p24config.enableTestMode(true);
Należy pamiętać, aby klucz CRC był ustawiony według wartości podanej w ustawieniach
konta SANDBOX.
Więcej o trybie testowym można znaleźć w punkcie 5.8 dokumentacji płatności www.
DialCom24 Sp. z o.o. Ul. Kanclerska 15, 60-327 Poznań, Polska
tel. +48 48 61 642 93 44 fax + 48 61 642 90 31 [email protected]
NIP 781-173-38-52, REGON 634509164, Sąd Rejonowy Poznań, VIII Wydz. Gospodarczy Krajowego Rejestru Sądowego
Nr KRS 0000306513, wysokość kapitału zakładowego: 1 697 000 zł
Strona 8 z 29
Płatności mobilne Przelewy24 – Specyfikacja techniczna
Opracował: Arkadiusz Macudziński
(Telefon 61 642 93 43)
1.8 Jak zweryfikować poprawność transakcji?
Transakcje wykonywane przez bibliotekę mogą być weryfikowane na dwa sposoby: za
pośrednictwem serwera partnera (rekomendowany), oraz wewnątrz systemu Przelewy24.
1.8.1 Weryfikacja za pośrednictwem serwera partnera
Po dokonaniu wpłaty biblioteka oczekuje na zaksięgowanie jej w systemie Przelewy24
(następuje to w różnym czasie, zależnie od metody płatności). W momencie zaksięgowania
wpłaty system Przelewy24 wysyła powiadomienie o transakcji na adres p24_url_status podany
przez partnera w konfiguracji. Serwer partnera po odebraniu powiadomienia musi wysłać do
Przelewy24 żądanie weryfikacji transakcji (punkt 5.5 dokumentacji płatności www). Biblioteka
wykrywa, że transakcja jest potwierdzona i wyświetla użytkownikowi informację o poprawnym
zaksięgowaniu wpłaty.
W tym wariancie partner ma pewność, że jego serwer posiada informację o dokonanej
wpłacie, nawet jak użytkownik zamknie okno biblioteki zanim transakcja zostanie
zweryfikowana, albo gdy nastąpi błąd połączenia z Internetem.
Aby uaktywnić ten tryb potwierdzania transakcji, należy ustawić parametr p24_url_status w
panelu transakcyjnym (w tym celu należy przesłać adres skryptu na [email protected] z
adresu e- mail, na który jest założone konto), albo w bibliotece:
p24payment.setP24UrlStatus("http://XXXXXX");
Ustawienie w bibliotece ma większy priorytet od ustawienia w panelu transakcyjnym. Jeżeli nie
ustawiono nigdzie p24_url_status, to transakcja będzie weryfikowana wewnątrz systemu
Przelewy24 (opisane poniżej).
Ten model weryfikacji dedykowany jest dla aplikacji, które wymagają, aby serwer partnera
posiadał informacje o wpłacie (np. doładowanie portfela, zakup usługi itp.).
1.8.2 Weryfikacja wewnątrz systemu Przelewy24
Po dokonaniu wpłaty i zaksięgowaniu jej przez system Przelewy24, transakcja zostaje
automatycznie potwierdzona przez system. Nie ma żadnej komunikacji z serwerem partnera,
informacja o poprawnej transakcji jest przekazana jedynie przez bibliotekę do aplikacji
mobilnej.
Aby uaktywnić ten tryb potwierdzania transakcji, należy zapewnić, aby ani w panelu
transakcyjnym, ani w konfiguracji biblioteki nie było ustawione p24_url_status. Ten model weryfikacji dedykowany jest dla aplikacji typu „gra”, które nie posiadają
komunikacji z zewnętrznym serwerem. Nie wymaga to od partnera tworzenia żadnych
dodatkowych usług weryfikacyjnych.
W tym trybie istnieje ryzyko, że zanim nastąpi weryfikacja transakcji w bibliotece, użytkownik
zamknie okno transakcji i powróci do aplikacji. Wtedy transakcja pozostanie zaksięgowana
jako „do wykorzystania” i będzie wymagała ręcznego zaksięgowania w panelu
transakcyjnym Przelewy24.
DialCom24 Sp. z o.o. Ul. Kanclerska 15, 60-327 Poznań, Polska
tel. +48 48 61 642 93 44 fax + 48 61 642 90 31 [email protected]
NIP 781-173-38-52, REGON 634509164, Sąd Rejonowy Poznań, VIII Wydz. Gospodarczy Krajowego Rejestru Sądowego
Nr KRS 0000306513, wysokość kapitału zakładowego: 1 697 000 zł
Strona 9 z 29
Płatności mobilne Przelewy24 – Specyfikacja techniczna
Opracował: Arkadiusz Macudziński
(Telefon 61 642 93 43)
1.9 Jak włączyć responsywne strony banków?
Ponieważ tylko niektóre banki udostępniają style mobilne w swoich serwisach transakcyjnych,
biblioteki mobilne same dostosowują strony banków do małych ekranów smartfonów, aby
zwiększyć wygodę użytkowania.
p24config.setUseMobileStyles(true);
Opcja ta domyślnie jest ustawiona na true, można ją wyłączyć.
Z przyczyn technologicznych style mobilne nie są dostępne w bibliotece Windows Phone
Silverlight.
1.10 Jak włączyć zapamiętywanie haseł do banków?
Aby ułatwić użytkownikom wielokrotne logowanie do swojego banku, biblioteka może
zapamiętać login i hasło i automatycznie uzupełnię je w formularzu logowania. W tym trybie
biblioteka również ułatwia wprowadzenie hasła maskowanego w bankach, które tego
wymagają.
p24config.setStoreLoginData(true);
Opcja ta domyślnie jest ustawiona na false.
1.11 Jak ustawić domyślnie zapamiętywanie haseł do banków?
Jeżeli opcja setStoreLoginData została ustawiona na true, to domyślnie biblioteka przy
pierwszym logowaniu do banku zapyta użytkownika czy wyraża zgodę na zapamiętywanie
danych logowania. Można wymusić zapamiętywanie danych logowania domyślnie, bez
pytania użytkownika (ale nawet wtedy będzie on miał możliwość wyłączenia tej opcji w
oknie „Opcje”).
p24config.setDontAskForSaveLoginData(true);
Opcja ta domyślnie jest ustawiona na false.
1.12 Jak włączyć automatyczne kopiowanie haseł SMS?
W momencie gdy na telefon przyjdzie SMS z hasłem do potwierdzenia płatności, biblioteka
automatycznie może go wykryć i wkleić hasło do odpowiedniego pola na stronie banku
(pod warunkiem, że użytkownik będzie dalej znajdował się na ekranie banku oczekującym
na hasło SMS). Użytkownik będzie musiał tylko zatwierdzić przelew.
p24config.setReadSmsPasswords(true)
Opcja ta domyślnie jest ustawiona na false.
Z przyczyn technologicznych opcja ta jest dostępna tylko na platformie Android.
DialCom24 Sp. z o.o. Ul. Kanclerska 15, 60-327 Poznań, Polska
tel. +48 48 61 642 93 44 fax + 48 61 642 90 31 [email protected]
NIP 781-173-38-52, REGON 634509164, Sąd Rejonowy Poznań, VIII Wydz. Gospodarczy Krajowego Rejestru Sądowego
Nr KRS 0000306513, wysokość kapitału zakładowego: 1 697 000 zł
Strona 10 z 29
Płatności mobilne Przelewy24 – Specyfikacja techniczna
1.13 Jak automatycznie powrócić
zakończenia transakcji?
do
Opracował: Arkadiusz Macudziński
(Telefon 61 642 93 43)
aplikacji
w
momencie
Domyślnie po zweryfikowaniu wpłaty (albo wystąpieniu błędu podczas płatności) biblioteka
wyświetla podsumowanie transakcji i czeka na interakcję z użytkownikiem (musi on
zatwierdzić okno podsumowania, aby wrócić do aplikacji). Można skonfigurować bibliotekę
tak, aby automatycznie zamykała okno podsumowania po określonym czasie podanym w
milisekundach.
p24config.setAutoFinishTimeout(3000);
Domyślna wartość to P24Config.NO_AUTO_FINISH = 0 – biblioteka czeka na reakcję
użytkownika aby wrócić do aplikacji.
Z racji zasad projektowania GUI na platformie iOS, opcja ta jest niedostępna na tej
platformie.
1.14 Jak ograniczyć
płatności?
klientowi
czas
dostępny
na
zrealizowanie
Można ustawić własny czas na realizację transakcji. Użytkownik będzie musiał zmieścić się z
wpłatą w określonym czasie.
p24config.setTimeLimit(30);
Domyślna wartość to 150 (min).
1.15 Jak anulować płatność i wrócić do aplikacji?
W każdym momencie procesu płatności użytkownik może porzucić płatność i powrócić do
aplikacji za pomocą przycisku „Powrót” (na Android i Windows Phone jest to przycisk
systemowy w telefonie, na iOS jest to przycisk programowy w górnym lewym rogu okna
biblioteki). Jeżeli w międzyczasie użytkownik przeszedł na stronę banku, to przy próbie
powrotu zostanie poinformowany, że jeżeli dokonał w międzyczasie wpłaty, to zostanie ona
zaksięgowana w tle i będzie musiał sprawdzić status wpłaty już wewnątrz aplikacji. Taki
komunikat jest konieczny, ponieważ jeżeli wiemy, iż użytkownik odwiedził bank, to nie jesteśmy
w stanie powiedzieć czy wywołał akcję powrót przed, czy po wykonaniu przelewu, jeżeli
wpłata nie została jeszcze zweryfikowana przez system Przelewy24.
1.16 Jak ustawić styl ActionBar biblioteki dla Androida < 3.0
Dla wersji Androida < 3.0 biblioteka sama tworzy ActionBar z opcjami. Jest możliwość
ustawienia własnych kolorów, aby były zgodne z wyglądem aplikacji:
p24config.setApi2ActionBarColor(int color);
p24config.setApi2ActionBarBottomLineColor(int color);
p24config.setApi2ActionBarTextColor(int color);
DialCom24 Sp. z o.o. Ul. Kanclerska 15, 60-327 Poznań, Polska
tel. +48 48 61 642 93 44 fax + 48 61 642 90 31 [email protected]
NIP 781-173-38-52, REGON 634509164, Sąd Rejonowy Poznań, VIII Wydz. Gospodarczy Krajowego Rejestru Sądowego
Nr KRS 0000306513, wysokość kapitału zakładowego: 1 697 000 zł
Strona 11 z 29
Płatności mobilne Przelewy24 – Specyfikacja techniczna
Opracował: Arkadiusz Macudziński
(Telefon 61 642 93 43)
2 Definicje
Sprzedawca - instytucja lub osoba prywatna korzystająca z usług serwisu PRZELEWY24.
Identyfikator sesji - unikalny identyfikator służący do weryfikacji danych pojedynczej
transakcji. Identyfikator ten pobierany jest od sprzedawcy.
CRC - losowy ciąg znaków służący do generowania sumy kontrolnej przesyłanych
parametrów, do pobrania z panelu Przelewy24.
3 Integracja biblioteki Android w projekcie aplikacji
W poniższym rozdziale opisany jest sposób konfiguracji i użycie Android SDK w projekcie
Android. Biblioteka w wersji od 2.0.6 jest kompatybilna ze środowiskiem AndroidStudio
(testowane na wersji 1.2.2).
3.1 Konfiguracja projektu
W projekcie Android należy ustawić wymagany API level na co najmniej 7 (Android 2.1).
Wersja 2.1 to minimalna wersja wymagana do poprawnego działania biblioteki.
W środowisku Android Studio należy dodać moduł biblioteki poprzez polecenie: „File → New
→ New module...”. Z listy „More modules” wybrać „Import .JAR or .AAR Package” i kliknąć
„Next”. W polu „File name” podać ścieżkę do pliku „p24Lib.aar”, jako „Subproject name”
podać „p24Lib” i kliknąć „Finish”.
Następnie należy dodać zależność do stworzonego modułu poprzez dodanie do pliku
„build.gradle” w sekcji „dependencies” wpisu:
compile project(':p24lib')
Biblioteka wykorzystuje bibliotekę AppCompat w wersji 21, dlatego należy w sekcji
„dependencies” dodać również:
compile 'com.android.support:appcompat-v7:22.1.+'
Biblioteka P24Lib korzysta z open source'owej biblioteki Jsoup (hqp://jsoup.org/) dołączonej
do biblioteki aar (nie wymaga dodatkowej konfiguracji).
Po podpięciu biblioteki do projektu należy dodać następujące wpisy do manifestu aplikacji
(AndroidManifest.xml), w węźle manifest:
<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
Jeżeli włączone jest automatyczne kopiowanie haseł SMS, należy dodać wpisy:
<uses-permission android:name="android.permission.RECEIVE_SMS"/>
<uses-featureandroid:name="android.hardware.telephony"
DialCom24 Sp. z o.o. Ul. Kanclerska 15, 60-327 Poznań, Polska
tel. +48 48 61 642 93 44 fax + 48 61 642 90 31 [email protected]
NIP 781-173-38-52, REGON 634509164, Sąd Rejonowy Poznań, VIII Wydz. Gospodarczy Krajowego Rejestru Sądowego
Nr KRS 0000306513, wysokość kapitału zakładowego: 1 697 000 zł
Strona 12 z 29
Płatności mobilne Przelewy24 – Specyfikacja techniczna
Opracował: Arkadiusz Macudziński
(Telefon 61 642 93 43)
android:required="false" />
W węźle application należy dodać aktywność TransferActivity (jest to aktywność, która jest
wykorzystywana do przeprowadzenia płatności):
<activity android:name="pl.dialcom24.p24lib.TransferActivity"
android:configChanges="orientation|keyboard|keyboardHidden"
android:theme="Theme.AppCompat.Light.DarkActionBar"/>
Uwaga – Wszystkie Activity w bibliotece dziedziczą po ActionBarActivity, dlatego należy do
nich stosować style z grupy „Theme.AppCompat.*" i pochodne.
Uwaga – przy domyślnych ustawieniach Activity podczas obrotu ekranu biblioteki nastąpi
przeładowanie WebView, co może powodować powrót ze strony banku do listy form
płatności i uniemożliwić sfinalizowanie transakcji. Aby okno biblioteki nie przeładowywało się
konieczne jest ustawienie parametru:
android:configChanges="orientation|keyboard|keyboardHidden"
W tym samym miejscu dodać aktywność BankListActivity (jest okno ustawień biblioteki, w
którym użytkownik sam będzie mógł sterować parametrami setStoreLoginData,
setUseMobileStyles, setReadSmsPasswords, oraz ręcznie usuwać zapamiętane hasła do
banków):
<activity android:name="pl.dialcom24.p24lib.bank.BankListActivity"
android:configChanges="keyboardHidden|orientation|keyboard|
screenSize" android:theme="Theme.AppCompat.Light.DarkActionBar"/>
3.2 Konfiguracja biblioteki
Należy utworzyć
konfiguracyjne:
obiekty
P24Config,
P24,
P24Payment
i
ustawić
niezbędne
dane
P24Config p24config = new P24Config();
P24 p24 = new P24(config);
P24Payment p24payment = new P24Payment();
Przykładowa konfiguracja przy wejściu bezpośrednio z danymi transakcji (pkt. 1.4.1):
p24config.setMerchantId("XXXXX");
p24config.setCrc("XXXXXXXXXXXXXXXX");
DialCom24 Sp. z o.o. Ul. Kanclerska 15, 60-327 Poznań, Polska
tel. +48 48 61 642 93 44 fax + 48 61 642 90 31 [email protected]
NIP 781-173-38-52, REGON 634509164, Sąd Rejonowy Poznań, VIII Wydz. Gospodarczy Krajowego Rejestru Sądowego
Nr KRS 0000306513, wysokość kapitału zakładowego: 1 697 000 zł
Strona 13 z 29
Płatności mobilne Przelewy24 – Specyfikacja techniczna
Opracował: Arkadiusz Macudziński
(Telefon 61 642 93 43)
p24payment.setSessionId("1234567890");
p24payment.setAmount(100);
p24payment.setCurrency("PLN");
p24payment.setClientAddress("Ulica testowa");
p24payment.setClientName("Jan Kowalski");
p24payment.setClientCountry("pl");
p24Payment.setClientCity("Poznan");
p24Payment.setClientPhone("643535555");
p24payment.setClientEmail("[email protected]");
Przykładowa konfiguracja przy wejściu z tokenem transakcji (pkt. 1.4.2):
p24payment.setToken("XXXXXXXXXX-XXXXXX-XXXXXX-XXXXXXXXXX");
Przykładowa konfiguracja opcjonalna (opisana powyżej):
p24payment.setMethod("1");
p24config.enableTestMode(true);
p24config.setStoreLoginData(true);
p24config.setUseMobileStyles(false);
p24config.setReadSmsPasswords(true);
p24config.setDontAskForSaveLoginData(true);
p24config.setAutoFinishTimeout(3000);
p24config.setTimeLimit(30);
p24config.setP24Channel(P24Config.P24_CHANNEL_CARDS);
p24payment.setP24UrlStatus("http://XXXXXX");
p24payment.setTransferLabel("Test label");
3.3 Wywołanie transakcji
Mając obiekty P24 oraz P24Payment można rozpocząć proces płatności. W tym celu należy
wykorzystać metodę P24.getPaymentIntent(Context, P24Payment): private final static int REQUEST_CODE = 25;
Intent pIntent = p24.getPaymentIntent(context, p24payment);
DialCom24 Sp. z o.o. Ul. Kanclerska 15, 60-327 Poznań, Polska
tel. +48 48 61 642 93 44 fax + 48 61 642 90 31 [email protected]
NIP 781-173-38-52, REGON 634509164, Sąd Rejonowy Poznań, VIII Wydz. Gospodarczy Krajowego Rejestru Sądowego
Nr KRS 0000306513, wysokość kapitału zakładowego: 1 697 000 zł
Strona 14 z 29
Płatności mobilne Przelewy24 – Specyfikacja techniczna
Opracował: Arkadiusz Macudziński
(Telefon 61 642 93 43)
startActivityForResult(pIntent, REQUEST_CODE);
Wywołanie powyższej metody spowoduje uruchomienie TransferActivity, które wyświetli okno
płatności. Użytkownik będzie mógł wybrać formę płatności (jeżeli nie ustawiono domyślnej
metody) i wykonać transakcję. Po przejściu przez proces płatności okno transakcyjne zostanie
zamknięte. Informacja na temat statusu płatności zostanie przekazana do metody
onActivityResult(int, int, Intent). Wewnątrz metody onActivityResult należy sprawdzić
poprawność parametrów requestCode i resultCode. resultCode powinien równać się stałej
RESULT_OK a requestCode powinien się zgadzać z liczbą REQUEST_CODE. Jeżeli wszystko się
zgadza, należy sprawdzić status transakcji. W tym celu należy pobrać obiekt
P24PaymentResult korzystając z metody P24.getPaymentResult(Intent). Jako parametr
przekazujemy Intent pochodzący z onActivityResult (jest to ten sam Intent, który został użyty
do rozpoczęcia procesu płatności):
@Override
protected void onActivityResult(int
data){
requestCode, int resultCode, Intent
if (requestCode != REQUEST_CODE) { return; }
if (resultCode == RESULT_OK) {
P24PaymentResult payResult = p24.getPaymentResult(data);
boolean isPaymentOk = payResult.isOk();
if (isPaymentOk) {
// transakcja zakończona sukcesem
} else {
// transakcja zakończona błędem
String error = payResult.getStatusMessage();
}
} else {
// transakcja została anulowana albo użytkownik wyszedł z biblioteki
// nie czekając na weryfikację wpłaty
}
}
3.4 Obfuskacja projektu aplikacji
Aby obfuskować projekt aplikacji z podpiętą biblioteką, należy dodać reguły do konfiguracji
proguard:
DialCom24 Sp. z o.o. Ul. Kanclerska 15, 60-327 Poznań, Polska
tel. +48 48 61 642 93 44 fax + 48 61 642 90 31 [email protected]
NIP 781-173-38-52, REGON 634509164, Sąd Rejonowy Poznań, VIII Wydz. Gospodarczy Krajowego Rejestru Sądowego
Nr KRS 0000306513, wysokość kapitału zakładowego: 1 697 000 zł
Strona 15 z 29
Płatności mobilne Przelewy24 – Specyfikacja techniczna
-keep
{ *; }
class
Opracował: Arkadiusz Macudziński
(Telefon 61 642 93 43)
pl.dialcom24.p24lib.TransferActivity$JavaScriptInterface
-keep class pl.dialcom24.p24lib.bank.jshelpers.JavaScriptInterface { *; }
-keep enum pl.dialcom24.p24lib.P24PaymentResultStatus { *; }
3.5 Znane błędy
Certyfikaty SSL Entrust na Android 4.3 – na niektórych kompilacjach Andorida 4.3 występuje
błąd podczas ładowania stron www, na których zainstalowany jest certyfikat firmy Entrust. Z
tego certyfikatu korzystają obecnie banki Alior i T-Mobile. Błąd powoduje wyłączenie się
aplikacji z błędem w momencie, gdy z listy form płatności zostanie wybrany jeden z tych
banków. Aktualnie nie jest znane skuteczne zabezpieczenie biblioteki przed tym błędem
(poza możliwością wyłączenia „wadliwych” form płatności dla wszystkich użytkowników z
Androidem 4.3). Pomocna dla użytkowników, którzy zgłaszają taki problem, może się okazać
sugestia aktualizacji systemu Android na telefonie.
Linki:
http://stackoverflow.com/questions/18130047/android-webview-crash-4-3
https://code.google.com/p/android/issues/detail?id=58400&colspec=ID%20Type%20Status
%20Owner %20Summary%20Stars
http://stackoverflow.com/questions/18824076/how-to-catch-this-excepjon-in-androidwebview
4 Integracja biblioteki iOS w projekcie aplikacji
Biblioteka iOS stworzona jest w języku Objective-C, w Xcode 4.3. W poniższym punkcie
opisany jest sposób konfiguracji i użycie iOS SDK w projekcie Xcode.
4.1 Konfiguracja projektu
W ustawieniach projektu Xcode nalezży ustawić „iOS Deployment Target” (zakładka „Info”
ustawień projektu) na wersję 4.3 lub nowszą. Wersja 4.3 to minimalna wersja systemu iOS
wymagana do poprawnego działania biblioteki.
Należy dodać pliki biblioteki (libP24.a, P24.h – znajdują się w katalogu lib/ w paczce ZIP z SDK)
do projektu. W tym celu należy:
•
wybrać w Xcode „File → Add Files To”,
•
wybrać katalog zawierający bibliotekę (katalog lib),
•
zaznaczyć opcję „Copy items into destination folder (if needed)”,
•
zaznaczyć opcję „Create groups for any added folders”,
DialCom24 Sp. z o.o. Ul. Kanclerska 15, 60-327 Poznań, Polska
tel. +48 48 61 642 93 44 fax + 48 61 642 90 31 [email protected]
NIP 781-173-38-52, REGON 634509164, Sąd Rejonowy Poznań, VIII Wydz. Gospodarczy Krajowego Rejestru Sądowego
Nr KRS 0000306513, wysokość kapitału zakładowego: 1 697 000 zł
Strona 16 z 29
Płatności mobilne Przelewy24 – Specyfikacja techniczna
•
Opracował: Arkadiusz Macudziński
(Telefon 61 642 93 43)
w polu „Add to targets” wybrać wszystkie elementy, do których ma zostać dodana
biblioteka.
Należy upewnić się, czy ustawienia Targetów zostały poprawnie zaktualizowane. Plik libP24.a
powinien zostać automatycznie dopisany w polu „Link Binary With Libraries” w zakładce
„Build Phases”. W tym celu należy: •
wybrać projekt w “Project Navigator”,
•
wybrać Target, w którym ma być używana biblioteka,
•
wybrać zakładkę “Build Phases”,
•
wybrać sekcję “Link Binary With Libraries”,
•
jeżeli plik libP24.a nie znajduje się na liście, należy przeciągnąć go z okna “Project
Navigator”,
•
powtórzyć powyższe kroki dla wszystkich Targetów, w których ma być wykorzystywana
biblioteka.
Należy dodać do Targetu wymagane biblioteki systemowe. Wymagane są następujące
biblioteki:
•
Security.Framework,
•
UIKit.Framework,
•
FoundaSon.Framework,
•
libxml2,
•
libz.
Biblioteki te należy dodać do sekcji „Link Binary With Libraries” w zakładce „Build Phases”.
Należy to wykonać dla każdego Targetu, w którym będzie wykorzystywana biblioteka.
Należy dodać flagi „JObjC” i „Jlstdc++” w polu „Other Linker Flags” w ustawieniach Targetu.
W tym celu należy:
•
wybrać zakładkę „Build Settings” w ustawieniach Targetu,
•
ustawić wartość pola „Other Linker Flags” na „-ObjC -lstdc++”. Pole „Other
Linker Flags” znajduje się w sekcji „Linking”,
•
powyższe kroki należy powtórzyć dla każdego Targetu, w którym biblioteka będzie
wykorzystywana.
Należy dodać poniższe ustawienie do pliku konfiguracyjnego Info.plist aplikacji:
<key>NSAppTransportSecurity</key>
DialCom24 Sp. z o.o. Ul. Kanclerska 15, 60-327 Poznań, Polska
tel. +48 48 61 642 93 44 fax + 48 61 642 90 31 [email protected]
NIP 781-173-38-52, REGON 634509164, Sąd Rejonowy Poznań, VIII Wydz. Gospodarczy Krajowego Rejestru Sądowego
Nr KRS 0000306513, wysokość kapitału zakładowego: 1 697 000 zł
Strona 17 z 29
Płatności mobilne Przelewy24 – Specyfikacja techniczna
Opracował: Arkadiusz Macudziński
(Telefon 61 642 93 43)
<dict>
<key>NSAllowsArbitraryLoads</key>
<true/>
</dict>
4.2 Konfiguracja biblioteki
Należy zaimportować plik P24.h, utworzyć obiekty P24Config, P24, P24Payment i ustawić
niezbędne dane konfiguracyjne:
P24Config *p24Config = [[P24Config alloc] init];
P24 *p24 = [[P24 alloc] initWithConfig:p24Config delegate:self];
P24Payment *p24Payment = [[P24Payment alloc] init];
Przykładowa konfiguracja przy wejściu bezpośrednio z danymi transakcji (pkt. 1.4.1):
p24Config.merchantId = @"XXXXX";
p24Config.crc = @"XXXXXXXXXXXXXXXX";
p24Payment.sessionId = @"1234567890";
p24Payment.amount = 100;
p24Payment.currency = @"PLN";
p24Payment.clientAddress = @"Ulica testowa";
p24Payment.clientCity = @"Poznan";
p24Payment.clientZipCode = @"61-600";
p24Payment.clientName = @"Jan Kowalski";
p24Payment.clientCountry = @"PL";
p24Payment.clientPhone = @"PL";
p24Payment.language = @"pl";
p24Payment.clientEmail = @"[email protected]";
Przykładowa konfiguracja przy wejściu z tokenem transakcji (pkt. 1.4.2):
p24payment.token = @"XXXXXXXXXX-XXXXXX-XXXXXX-XXXXXXXXXX";
Przykładowa konfiguracja opcjonalna (opisana powyżej):
p24payment.method = @"XXX";
DialCom24 Sp. z o.o. Ul. Kanclerska 15, 60-327 Poznań, Polska
tel. +48 48 61 642 93 44 fax + 48 61 642 90 31 [email protected]
NIP 781-173-38-52, REGON 634509164, Sąd Rejonowy Poznań, VIII Wydz. Gospodarczy Krajowego Rejestru Sądowego
Nr KRS 0000306513, wysokość kapitału zakładowego: 1 697 000 zł
Strona 18 z 29
Płatności mobilne Przelewy24 – Specyfikacja techniczna
Opracował: Arkadiusz Macudziński
(Telefon 61 642 93 43)
[p24Config.enableTestMode: YES];
p24config.storeLoginData = YES;
p24config.useMobileStyles = NO;
p24config.dontAskForSaveLoginData = YES;
p24config.timeLimit = 30;
p24config.p24Channel = P24_CHANNEL_CARDS;
p24payment.p24UrlStatus = @"http://XXXXXX";
p24payment.transferLabel = @"Test label";
4.3 Wywołanie transakcji
Należy zaimplementować w kontrolerze protokół P24Delegate (zawiera on metody służące
do informowania o statusie płatności) - (void)p24:(P24 *)p24 didFinishPayment:(P24Payment *)p24Payment
withResult:(P24PaymentResult *)p24PaymentResult {
BOOL paymentOk = [p24PaymentResult isOk];
if (!paymentOK) {
NSLog(@”Payment error: %d, %@”, p24PaymentResult.status.code,
p24PaymentResult.status.description);
}
- (void)p24:(P24 *)p24 didCancelPayment:(P24Payment *)p24Payment {
// transakcja została anulowana albo użytkownik wyszedł z biblioteki
// nie czekając na weryfikację wpłaty
}
- (void)p24:(P24 *)p24 didFailPayment:(P24Payment *)p24Payment
withError:(NSError *)error {}
Mając obiekty P24 oraz P24Payment można rozpocząć proces płatności. W tym celu
należy wykorzystać metodę startPayment:inViewController: z klasy P24:
[p24 startPayment:p24Payment inViewController:self];
DialCom24 Sp. z o.o. Ul. Kanclerska 15, 60-327 Poznań, Polska
tel. +48 48 61 642 93 44 fax + 48 61 642 90 31 [email protected]
NIP 781-173-38-52, REGON 634509164, Sąd Rejonowy Poznań, VIII Wydz. Gospodarczy Krajowego Rejestru Sądowego
Nr KRS 0000306513, wysokość kapitału zakładowego: 1 697 000 zł
Strona 19 z 29
Płatności mobilne Przelewy24 – Specyfikacja techniczna
Opracował: Arkadiusz Macudziński
(Telefon 61 642 93 43)
Wywołanie powyższej metody spowoduje wyświetlenie okna płatności. Użytkownik będzie
mógł wybrać formę płatności (jeżeli nie ustawiono domyślnej metody) i wykonać transakcję.
Po przejściu przez proces płatności okno transakcyjne zostanie zamknięte. Informacja na
temat statusu płatności zostanie przekazana do jednej z metod protokołu P24Delegate.
5 Integracja biblioteki Windows Phone w projekcie aplikacji
Biblioteka Windows Phone stworzona jest w języku C#. W poniższym punkcie opisany jest
sposób konfiguracji i użycie Windows Phone SDK w projekcie Visual Studio.
UWAGA: Aktualnie w bibliotekach Windows Phone są niedostępne półautomatyczne formy
płatności (e-przelewy). Zostaną one dodane w przyszłości.
5.1 Konfiguracja projektu
5.1.1 Windows Phone Silverlight
W ustawieniach projektu należy ustawić wersję Windows Phone (Target Windows Phone OS
Version). Minimalna wersja Windows Phone, z jaką współpracuje biblioteka, to 8.1.
Do projektu należy dodać referencje do trzech bibliotek (znajdują się w katalogu lib/ w
paczce ZIP z SDK):
•
Biblioteka DialCom24.P24Lib.dll,
•
BouncyCastle.Crypto.WP7.dll,
•
HtmlAgilityPack.dll
5.1.2 Windows Phone Runtime
Do projektu aplikacji Windows Phone 8.1 należy skopiować cały katalog lib/ znajdujący się w
paczce paczce ZIP z SDK. W projekcie dodać referencje do trzech bibliotek znajdujących się
w tym katalogu:
•
DialCom24.P24Lib.Runtime.dll,
•
crypto.dll,
•
HtmlAgilityPack.dll
W manifeście aplikacji (Package.appxmanifest) w zakładce „Content URIs” dodać wpisy:
https://secure.przelewy24.pl/*
https://www.przelewy24.pl/*
DialCom24 Sp. z o.o. Ul. Kanclerska 15, 60-327 Poznań, Polska
tel. +48 48 61 642 93 44 fax + 48 61 642 90 31 [email protected]
NIP 781-173-38-52, REGON 634509164, Sąd Rejonowy Poznań, VIII Wydz. Gospodarczy Krajowego Rejestru Sądowego
Nr KRS 0000306513, wysokość kapitału zakładowego: 1 697 000 zł
Strona 20 z 29
Płatności mobilne Przelewy24 – Specyfikacja techniczna
Opracował: Arkadiusz Macudziński
(Telefon 61 642 93 43)
5.2 Konfiguracja biblioteki
Należy utworzyć
konfiguracyjne:
obiekty
P24Config,
P24,
P24Payment
i
ustawić
niezbędne
dane
P24Config p24config = new P24Config();
P24 p24 = new P24(p24config);
P24Payment p24payment = new P24Payment();
Przykładowa konfiguracja przy wejściu bezpośrednio z danymi transakcji (pkt. 1.4.1):
p24config.MerchantId = "XXXXX";
p24config.Crc = "XXXXXXXXXXXXXXXX";
p24config.SessionId = "1234567890";
p24config.Amount = 100;
p24config.Language = "pl";
p24config.Currency = "PLN";
p24config.ClientAddress = "Ulica testowa";
p24config.ClientCity = "Poznan";
p24config.ClientZipCode = "61-600";
p24config.ClientName = "Jan Kowalski";
p24config.ClientCountry = "PL";
p24config.ClientPhone = "600600600";
p24config.ClientEmail = "[email protected]";
Przykładowa konfiguracja przy wejściu z tokenem transakcji (pkt. 1.4.2):
p24payment.Token = "XXXXXXXXXX-XXXXXX-XXXXXX-XXXXXXXXXX";
Przykładowa konfiguracja opcjonalna (opisana powyżej):
p24payment.Method = "XXX";
p24config.TestMode = true;
p24config.SaveLoginData = true;
p24config.UseMobileStyles = true; //tylko Windows Phone Runtime
p24config.AutoFinishTimeout = 3000;
p24config.DontAskForSaveLoginData = true;
DialCom24 Sp. z o.o. Ul. Kanclerska 15, 60-327 Poznań, Polska
tel. +48 48 61 642 93 44 fax + 48 61 642 90 31 [email protected]
NIP 781-173-38-52, REGON 634509164, Sąd Rejonowy Poznań, VIII Wydz. Gospodarczy Krajowego Rejestru Sądowego
Nr KRS 0000306513, wysokość kapitału zakładowego: 1 697 000 zł
Strona 21 z 29
Płatności mobilne Przelewy24 – Specyfikacja techniczna
Opracował: Arkadiusz Macudziński
(Telefon 61 642 93 43)
p24config.TimeLimit = 30;
p24payment.P24UrlStatus("http://XXXXXX");
p24payment.TransferLabel = "Test label";
Biblioteka Windows Phone posiada dodatkowe parametry. P24config.WithStatusBar pozwala
wyłączyć status bar w oknie biblioteki. P24config.ManuWithIconButtons pozwala na użycie
ikon w menu biblioteki. Domyślnie opcje menu okna transakcji wyświetlają się jako
ApplicationBarMenuItem. Aby wyświetlać opcje jako ikony należy dołączyć do projektu
aplikacji katalog „/Images” z grafikami i ustawić dla grafik „Build Action – Content” i „Copy to
Output Directory - Copy if never” (przykład w projekcie DialCom24.P24Example), oraz ustawić
parametr p24config.ManuWithIconButtons na true.
p24config.WithStatusBar = false;
p24config.ManuWithIconButtons = true;
5.3 Wywołanie transakcji
Mając obiekt P24 oraz P24Payment można rozpocząć proces płatności. W tym celu należy
wykorzystać poniższy kod:
//Windows Phone Silverlight
Uri uri = p24.GetStartPaymentUri(payment);
NavigationService.Navigate(uri);
//Windows Phone Runtime
Frame.Navigate(p24.GetStartPaymentParam(payment));
Pojawi się okno płatności, w którym użytkownik będzie mógł wybrać sposób płatności i
wykonać wpłatę. Po przejściu przez proces płatności, użytkownik zostanie przekierowany z
powrotem do okna, z którego wywołał bibliotekę. Wynik płatności można uzyskać po
przeładowaniu metody OnNavigatedTo(NavigationEventArgs e) okna, z którego
wywoływaliśmy bibliotekę:
protected override void
OnNavigatedTo(System.Windows.Navigation.NavigationEventArgs e) {
base.OnNavigatedTo(e);
if (p24.IsPaymentCompleted) {
if (p24.IsPaymentCancelled) {
//transakcja została anulowana albo użytkownik wyszedł z biblioteki
DialCom24 Sp. z o.o. Ul. Kanclerska 15, 60-327 Poznań, Polska
tel. +48 48 61 642 93 44 fax + 48 61 642 90 31 [email protected]
NIP 781-173-38-52, REGON 634509164, Sąd Rejonowy Poznań, VIII Wydz. Gospodarczy Krajowego Rejestru Sądowego
Nr KRS 0000306513, wysokość kapitału zakładowego: 1 697 000 zł
Strona 22 z 29
Płatności mobilne Przelewy24 – Specyfikacja techniczna
Opracował: Arkadiusz Macudziński
(Telefon 61 642 93 43)
// nie czekając na weryfikację wpłaty
} else {
P24PaymentResult result = p24.PaymentResult;
if (result.IsOK) {
// transakcja zakończona poprawnie
string sessionId = result.SessionId;
int orderId = result.OrderId;
long orderIdFull = result.OrderIdFull;
int amount = result.Amount;
string currency = result.Currency;
} else { /* blad podczas platnosci */ }
}
}
}
Wynik płatności jest dostępny w obiekcie P24PaymentResult.
DialCom24 Sp. z o.o. Ul. Kanclerska 15, 60-327 Poznań, Polska
tel. +48 48 61 642 93 44 fax + 48 61 642 90 31 [email protected]
NIP 781-173-38-52, REGON 634509164, Sąd Rejonowy Poznań, VIII Wydz. Gospodarczy Krajowego Rejestru Sądowego
Nr KRS 0000306513, wysokość kapitału zakładowego: 1 697 000 zł
Strona 23 z 29
Płatności mobilne Przelewy24 – Specyfikacja techniczna
Opracował: Arkadiusz Macudziński
(Telefon 61 642 93 43)
Załącznik nr 1 – Historia zmian dokumentu
Data
2015-08-17
2015-08-20
2015-08-24
Autor
Arkadiusz
Macudziński
Arkadiusz
Macudziński
Arkadiusz
Macudziński
2015-08-26
Arkadiusz
Macudziński
2015-08-27
Arkadiusz
Macudziński
Arkadiusz
Macudziński
Arkadiusz
Macudziński
2015-08-28
2015-10-30
Uwagi
Opracowanie dokumentu
Dodanie historii zmian bibliotek mobilnych
Wersja 2.0.1 - dodanie opisu p24_channel i p24_method przy
rejestracji
transakcji,
dodanie
opisu
zabezpieczenia
obracania ekranu w bibliotece Android
Wersja 2.0.2 - aktualizacja opisu biblioteki Windows Phone
pod wersję 2.0.0 – nieznaczna zmiana konfiguracji i nowe
opcje
Wersja 2.0.4 - aktualizacja biblioteki Android do wersji 2.0.5
Wersja 2.0.5 - aktualizacja biblioteki iOS do wersji 2.0.3 i
Windows Phone do wersji 2.0.1
Wersja 2.0.6 – zmiana opisu integracji biblioteki Android w
związku z przejściem z Eclipse do Android Studio i integracją z
biblioteką appcompat.
DialCom24 Sp. z o.o. Ul. Kanclerska 15, 60-327 Poznań, Polska
tel. +48 48 61 642 93 44 fax + 48 61 642 90 31 [email protected]
NIP 781-173-38-52, REGON 634509164, Sąd Rejonowy Poznań, VIII Wydz. Gospodarczy Krajowego Rejestru Sądowego
Nr KRS 0000306513, wysokość kapitału zakładowego: 1 697 000 zł
Strona 24 z 29
Płatności mobilne Przelewy24 – Specyfikacja techniczna
Opracował: Arkadiusz Macudziński
(Telefon 61 642 93 43)
Załącznik nr 2 – Historia zmian biblioteki Android
Data
2012-09-01
2013-06-04
2013-06-27
2013-07-18
2013-09-13
2013-10-17
2013-10-18
2013-10-25
2013-11-14
2013-12-02
2013-12-03
2013-12-09
2013-12-17
2014-01-02
2014-01-13
2014-02-03
2014-02-05
2014-02-05
2014-02-25
2014-03-07
2014-08-25
2014-09-03
Autor
Arkadiusz
Macudziński
Arkadiusz
Macudziński
Arkadiusz
Macudziński
Arkadiusz
Macudziński
Arkadiusz
Macudziński
Arkadiusz
Macudziński
Arkadiusz
Macudziński
Arkadiusz
Macudziński
Arkadiusz
Macudziński
Arkadiusz
Macudziński
Arkadiusz
Macudziński
Arkadiusz
Macudziński
Arkadiusz
Macudziński
Arkadiusz
Macudziński
Arkadiusz
Macudziński
Arkadiusz
Macudziński
Arkadiusz
Macudziński
Arkadiusz
Macudziński
Arkadiusz
Macudziński
Arkadiusz
Macudziński
Arkadiusz
Macudziński
Arkadiusz
Uwagi
Opracowanie dokumentacji
Aktualizacja do wersji 1.4.0
Aktualizacja do wersji 1.4.2
Wersja 1.4.3 – drobne poprawki, bez zmian funkcjonalności i
API
Wersja 1.4.3 – dodanie opisu konfiguracji połączenia
biblioteki z serwerem sandbox.
Wersja 1.4.4 – poprawka przeklejania sms.
Wersja 1.4.5 – zmieniono domyślne ustawienie zapisywania
danych logowania i sms.
Wersja 1.4.6 – hasła i sms dla nowych banków.
Wersja 1.4.7 – poprawiony błąd
niepotwierdzonych
transakcji
Wersja 1.5.0 – style mobilne na stronach banków,
poprawiono kodowanie maila z powiadomieniem o
transakcji, poprawiono przesyłanie parametru p24_city
(ważne dla płatności kartą)
Wersja 1.5.1 – reguły potrzebne do obfuskacji boblioteki,
refaktoryzacja
Wersja 1.5.2 – dodanie konfiguracji stylów mobilnych
banków, poprawiono działanie konfiguracji biblioteki
Wersja 1.5.3 – poprawki drobnych błędów
Wersja 1.5.4 – poprawka błędu przy konfiguracji apiLevel=17
na telefonie z Androidem 4.2+
Wersja 1.5.5 – dodanie parametru P24Payment.setMethod
Wersja 1.5.6 – zmiana zoomowania stron banków na
klasyczne (dotyczy stron bez stylów mobilnych), poprawka
komunikatu „Ładowanie”, przeniesienie przycisków „Zmień
bank” i „Zakończ transakcję” do ActionBar'a (jeżeli jest
aktywny).
Wersja 1.5.7 – poprawka błędu WebView przy zamykaniu
okna
Wersja 1.5.8 – bugfix, obsługa błędu autoryzacji certyfikatów,
style mobilne dla Androida 2.1
Wersja 1.5.9 – wyłączenie priorytetu renderowania strony w
WebView (to ustawienie powodowało zawieszanie aplikacji
skonwertowanej na Blackberry < 10.2)
Wersja 1.6.0 – implementacja dokumentacji 3.1 – dodanie
P24Payment.setToken(String).
Poprawka
opisu
implementacji
automatycznego
powiadamiania o transakcji
Obsługa automatycznego powiadamiania o wyniku
DialCom24 Sp. z o.o. Ul. Kanclerska 15, 60-327 Poznań, Polska
tel. +48 48 61 642 93 44 fax + 48 61 642 90 31 [email protected]
NIP 781-173-38-52, REGON 634509164, Sąd Rejonowy Poznań, VIII Wydz. Gospodarczy Krajowego Rejestru Sądowego
Nr KRS 0000306513, wysokość kapitału zakładowego: 1 697 000 zł
Strona 25 z 29
Płatności mobilne Przelewy24 – Specyfikacja techniczna
2015-05-22
2015-06-05
2015-06-19
2015-07-20
2015-08-20
2015-08-27
2015-10-30
Macudziński
Arkadiusz
Macudziński
Arkadiusz
Macudziński
Arkadiusz
Macudziński
Arkadiusz
Macudziński
Arkadiusz
Macudziński
Arkadiusz
Macudziński
Arkadiusz
Macudziński
Opracował: Arkadiusz Macudziński
(Telefon 61 642 93 43)
transakcji zgodnie z dokumentacją 3.2
Wersja 2.0.0 – dodanie obsługi e-przelewów, rezygnacja z
kompatybilności z dokumentacją 2.x, przeredagowanie
dokumentacji, dodanie pytania użytkownika o zapisywanie
danych logowania, dodanie zapamiętywania haseł
maskowanych
Wersja 2.0.1 – poprawka płatności e-przelewami
Wersja
2.0.2
–
poprawka
działania
parametru
dontAskForSaveLoginData, poprawka ustawienia opisu
transakcji
Wersja 2.0.3 – poprawka P24PaymentResultStatus
Wersja 2.0.4 - dodanie parametru
P24Payment.setClientPhone()
Wersja 2.0.5 - dodanie parametru
P24Payment.setTransferLabel(), angielska wersja językowa
Wersja 2.0.6 – zmiana biblioteki z formatu jar na aar,
przykładowy projekt w AndroidStudio, integracja z biblioteką
appcompat (dodanie dziedziczenia TransferActivity i
BankListActivity po ActionBarActivity). Zmiana sposobu
konfiguracji biblioteki w projekcie Android Studio.
Optymalizacja przeładowywania ekranów przy wykonywaniu
e-przelewów.
DialCom24 Sp. z o.o. Ul. Kanclerska 15, 60-327 Poznań, Polska
tel. +48 48 61 642 93 44 fax + 48 61 642 90 31 [email protected]
NIP 781-173-38-52, REGON 634509164, Sąd Rejonowy Poznań, VIII Wydz. Gospodarczy Krajowego Rejestru Sądowego
Nr KRS 0000306513, wysokość kapitału zakładowego: 1 697 000 zł
Strona 26 z 29
Płatności mobilne Przelewy24 – Specyfikacja techniczna
Opracował: Arkadiusz Macudziński
(Telefon 61 642 93 43)
Załącznik nr 3 – Historia zmian biblioteki iOS
Data
2013-06-13
2013-09-13
2013-10-31
2013-11-07
2013-11-07
2013-11-20
2013-12-03
2013-12-13
Autor
Arkadiusz
Macudziński
Arkadiusz
Macudziński
Arkadiusz
Macudziński
Arkadiusz
Macudziński
Arkadiusz
Macudziński
Arkadiusz
Macudziński
Arkadiusz
Macudziński
Arkadiusz
Macudziński
2014-01-10
Arkadiusz
Macudziński
2014-03-13
Arkadiusz
Macudziński
Arkadiusz
Macudziński
Arkadiusz
Macudziński
Arkadiusz
Macudziński
Arkadiusz
Macudziński
Arkadiusz
Macudziński
Arkadiusz
Macudziński
2014-04-07
2014-06-18
2014-08-25
2014-09-03
2014-10-24
2015-05-22
2015-06-30
Arkadiusz
Macudziński
2015-08-20
Arkadiusz
Macudziński
2015-08-28
Arkadiusz
Macudziński
2015-10-30
Arkadiusz
Macudziński
Uwagi
Opracowanie dokumentacji
Dodano opis konfiguracji połączenia biblioteki z serwerem
sanbox
Wersja 1.2.3 – dodanie nowych banków, domyślnie
ustawione zapisywanie haseł do banków, dodana
zgodność z iOS7
Wersja 1.2.4 – poprawki błędów
Wersja 1.3.0 – dodanie stylów mobilnych do stron banków,
poprawki błędów
Wersja 1.3.1 – automatyczne aktualizowanie zmian w
konfiguracji i stylach stron banków. Zmiana konfiguracji
projektu (dodanie flagi -lstdc++ i biblioteki systemowej libz)
Wersja 1.3.2 – bugfix
Wersja 1.3.3 – poprawiono parametr p24_encoding,
poprawiono wydajność biblioteki podczas korzystania ze
stylów mobilnych, dodano opcję stylów mobilnych w
konfiguracji
Wersja 1.3.4 – dodano możliwość ustawienia domyślnej
metody płatności w bibliotece (P24Payment.method),
poprawki graficzne pod iOS7
Wersja 1.3.5 – poprawka ładowania niektórych stron
banków
Wersja 1.4.0 – implementacja dokumentacji 3.1 – dodanie
P24Payment.token. Kompatybilność z architekturą arm64.
Wersja 1.4.1 – wyłączenie trybu modal dla iPada.
Poprawka
opisu
implementacji
automatycznego
powiadamiania o transakcji
Wersja 1.4.2 – obsługa automatycznego powiadamiania o
wyniku transakcji zgodnie z dokumentacją 3.2
Wersja 1.4.3 – poprawka błędu z p24UrlStatus, dodanie
opcji ustawienia kolorów przycisków opcji w navigationBar
Wersja 2.0.0 – dodanie obsługi e-przelewów, rezygnacja z
kompatybilności z dokumentacją 2.x, przeredagowanie
dokumentacji, dodanie pytania użytkownika o zapisywanie
danych logowania, dodanie zapamiętywania haseł
maskowanych
Wersja
2.0.1
poprawka
działania
parametru
dontAskForSaveLoginData, poprawka ustawienia opisu
transakcji
Wersja 2.0.2 - dodanie parametru p24Payment.clientPhone
Wersja
2.0.3
dodanie
parametru
P24Payment.transferLabel, angielska wersja językowa,
dodanie P24_CHANNEL_PBL
Wersja 2.0.4 – poprawka przełączania wersji językowej pod
iOS 9
DialCom24 Sp. z o.o. Ul. Kanclerska 15, 60-327 Poznań, Polska
tel. +48 48 61 642 93 44 fax + 48 61 642 90 31 [email protected]
NIP 781-173-38-52, REGON 634509164, Sąd Rejonowy Poznań, VIII Wydz. Gospodarczy Krajowego Rejestru Sądowego
Nr KRS 0000306513, wysokość kapitału zakładowego: 1 697 000 zł
Strona 27 z 29
Płatności mobilne Przelewy24 – Specyfikacja techniczna
2016-01-29
Arkadiusz
Macudziński
Opracował: Arkadiusz Macudziński
(Telefon 61 642 93 43)
Dodanie opisu konfiguracji Info.plist dla iOS 9
DialCom24 Sp. z o.o. Ul. Kanclerska 15, 60-327 Poznań, Polska
tel. +48 48 61 642 93 44 fax + 48 61 642 90 31 [email protected]
NIP 781-173-38-52, REGON 634509164, Sąd Rejonowy Poznań, VIII Wydz. Gospodarczy Krajowego Rejestru Sądowego
Nr KRS 0000306513, wysokość kapitału zakładowego: 1 697 000 zł
Strona 28 z 29
Płatności mobilne Przelewy24 – Specyfikacja techniczna
Opracował: Arkadiusz Macudziński
(Telefon 61 642 93 43)
Załącznik nr 4 – Historia zmian biblioteki Windows Phone
Data
2013-05-27
2013-07-09
2013-07-23
2013-07-26
2013-09-13
2013-09-23
2014-03-07
2014-04-07
2014-08-35
2014-09-03
2014-12-01
2015-02-13
2015-05-27
2015-08-26
2015-08-28
2015-10-30
2016-02-05
Autor
Arkadiusz
Macudziński
Arkadiusz
Macudziński
Arkadiusz
Macudziński
Arkadiusz
Macudziński
Arkadiusz
Macudziński
Arkadiusz
Macudziński
Arkadiusz
Macudziński
Arkadiusz
Macudziński
Arkadiusz
Macudziński
Arkadiusz
Macudziński
Arkadiusz
Macudziński
Arkadiusz
Macudziński
Arkadiusz
Macudziński
Arkadiusz
Macudziński
Arkadiusz
Macudziński
Arkadiusz
Macudziński
Arkadiusz
Macudziński
Uwagi
Opracowanie dokumentacji
Aktualizacja informacji kontaktowych w dokumencie
Drobne poprawki biblioteki, możliwość konfiguracji status
bara przez P24Config
Wersja 1.0.2 – zablokowanie poruszania ekranem listy metod
płatności
Dodanie opisu konfiguracji biblioteki z serwerem sandbox
Wersja 1.0.3 – drobne poprawki graficzne i wydajnościowe.
Poprawiony problem zawieszania się pod Windows Phone 8.
Wersja 1.1.0 – zmiany graficzne, zapisywanie danych
logowania, autozamykanie podsumowania transakcji
Wersja 1.2.0 – implementacja dokumentacji 3.1 – dodanie
P24Payment.Token
Poprawka
opisu
implementacji
automatycznego
powiadamiania o transakcji
Wersja 1.2.1 - obsługa automatycznego powiadamiania o
wyniku transakcji zgodnie z dokumentacją 3.2
Wersja 1.2.2 – poprawka powiadamiania o wyniku transakcji
zgodnie z dokumentacją 3.2
Wersja 1.2.2.1 - bugfix
Wersja 1.2.3 – poprawka błędu cofania przy ustawieniu
P24Payment.Method
Wersja 2.0.0 – kompatybilność z Windows Phone od wersji 8.0,
rezygnacja z kompatybilności z dokumentacją Przelewy24
2.x, dodanie pytania użytkownika o zapisywanie danych
logowania, dodanie zapamiętywania haseł maskowanych,
dodanie weryfikacji transakcji z użyciem serwera partnera
Wersja 2.0.1 - dodanie parametru P24Payment.TransferLabel,
angielska wersja językowa
Wersja 2.0.2 – poprawiono problem z płatnością przelewem z
banków ING i Pekao S.A., kompatybilność z systemem
Windows Phone od wersji 8.1 (poprawka dla banku ING
wymagała kompilacji biblioteki na WP 8.1)
Wersja 2.0.3 – biblioteka Windows Phone od wersji 2.0.3
wspiera tylko platformę Windows Phone Runtime. Dodano
style mobilne.
DialCom24 Sp. z o.o. Ul. Kanclerska 15, 60-327 Poznań, Polska
tel. +48 48 61 642 93 44 fax + 48 61 642 90 31 [email protected]
NIP 781-173-38-52, REGON 634509164, Sąd Rejonowy Poznań, VIII Wydz. Gospodarczy Krajowego Rejestru Sądowego
Nr KRS 0000306513, wysokość kapitału zakładowego: 1 697 000 zł
Strona 29 z 29

Podobne dokumenty