Płatności mobilne Przelewy24

Transkrypt

1 Opracował: Arkadiusz Płatności mobilne Przelewy24 Specyfikacja techniczna Data: Wersja: 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 Dokumentacja odnosi się do bibliotek mobilnych w wersjach: Android v , ios v , Windows Phone v UWAGA! Aby otrzymywać powiadomienia o aktualizacjach bibliotek mobilnych, należy wysłać na adres partner@przelewy24.pl wiadomość o treści "Proszę o dopisanie adresu (tu podać ) do listy mailingowej informującej o aktualizacjach bibliotek mobilnych.", podając swój 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. Strona 1 z 27

2 Opracował: Arkadiusz Spis treści 1 Natywne biblioteki mobilne (Android, ios i Windows Phone SDK) Opis zastosowania Jak wygląda przebieg transakcji przy użyciu biblioteki mobilnej? Jak zaimplementować w aplikacji płatność one click kartą? Jak zainicjować płatność biblioteką mobilną? Wejście bezpośrednio z danymi transakcji Wejście z tokenem transakcji Jak uruchomić transakcję z konkretną metodą płatność? Jak ustawić konkretny kanał płatności? Jak uruchomić tryb testowy? Jak zweryfikować poprawność transakcji? Weryfikacja za pośrednictwem serwera partnera Weryfikacja wewnątrz systemu Przelewy Jak włączyć responsywne strony banków? Jak włączyć zapamiętywanie haseł do banków? Jak ustawić domyślnie zapamiętywanie haseł do banków? Jak włączyć automatyczne kopiowanie haseł SMS? Jak automatycznie powrócić do aplikacji w momencie zakończenia transakcji? Jak ograniczyć klientowi czas dostępny na zrealizowanie płatności? Jak anulować płatność i wrócić do aplikacji? Jak ustawić styl ActionBar biblioteki dla Androida < Definicje Integracja biblioteki Android w projekcie aplikacji Konfiguracja projektu Konfiguracja biblioteki Wywołanie transakcji Obfuskacja projektu aplikacji...15 Strona 2 z 27

3 Opracował: Arkadiusz 3.5 Znane błędy Integracja biblioteki ios w projekcie aplikacji Konfiguracja projektu Konfiguracja biblioteki Wywołanie transakcji Integracja biblioteki Windows Phone w projekcie aplikacji Konfiguracja projektu Konfiguracja biblioteki Wywołanie transakcji...21 Strona 3 z 27

4 Opracował: Arkadiusz 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. Strona 4 z 27

5 Opracował: Arkadiusz 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 Strona 5 z 27

6 Opracował: Arkadiusz aplikacji jako osobną formę płatności. W momencie wybrania tej karty, aplikacja wywołuje 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 (partner@przelewy24.pl, ). 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ść. Strona 6 z 27

7 Opracował: Arkadiusz 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). 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 komunika 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 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 ), 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 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. Strona 7 z 27

8 Opracował: Arkadiusz 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 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 ), 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); Strona 8 z 27

9 Opracował: Arkadiusz 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. 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 Przelewy 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 serwis@przelewy24.pl z adresu e- mail, na który jest założone konto), albo w bibliotece: p24payment.setp24urlstatus(" 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.) 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. Strona 9 z 27

10 Opracował: Arkadiusz 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 Przelewy 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 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 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 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. Strona 10 z 27

11 Opracował: Arkadiusz 1.13 Jak automatycznie powrócić do aplikacji w momencie zakończenia transakcji? 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 Jak ograniczyć klientowi czas dostępny na zrealizowanie płatności? 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) 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 Przelewy 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); Strona 11 z 27

12 Opracował: Arkadiusz 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 punkcie opisany jest sposób konfiguracji i użycie Android SDK w projekcie Android. 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. Do projektu należy dodać dwie biblioteki jar (znajdują się w katalogu lib/ w paczce ZIP z SDK): bibliotekę Przelewy24,bibliotekę Jsoup (hqp://jsoup.org/). 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" 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="@android:style/theme.holo.light.darkactionbar"/> Uwaga TransferActivity posiada menu z opcjami, dlatego styl dla tego okna dla Androida 3.0+ powinien mieć włączony ActionBar (nie używać stylów FullScreen, NoActionBar). Na Strona 12 z 27

13 Opracował: Arkadiusz niektórych nowszych telefonach może nie być przycisku Menu, w związku z czym może nie być dostępu do ustawień okna płatności. Domyślny styl, 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"/> 3.2 Konfiguracja biblioteki Należy utworzyć obiekty P24Config, P24, P24Payment i ustawić niezbędne dane konfiguracyjne: 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 ): p24config.setmerchantid("xxxxx"); p24config.setcrc("xxxxxxxxxxxxxxxx"); p24payment.setsessionid(" "); p24payment.setamount(100); p24payment.setcurrency("pln"); p24payment.setclientaddress("ulica testowa"); p24payment.setclientname("jan Kowalski"); p24payment.setclientcountry("pl"); Strona 13 z 27

14 Opracował: Arkadiusz p24payment.setclientcity("poznan"); p24payment.setclientphone(" "); Przykładowa konfiguracja przy wejściu z tokenem transakcji (pkt ): 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(" 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); 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 Strona 14 z 27

15 Opracował: Arkadiusz przekazujemy Intent pochodzący z onactivityresult (jest to ten sam Intent, który został użyty do rozpoczęcia procesu protected void onactivityresult(int requestcode, int resultcode, Intent data){ } 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 { } } else { // transakcja zakończona błędem String error = payresult.getstatusmessage(); // 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: -keep class pl.dialcom24.p24lib.transferactivity$javascriptinterface { *; } -keep class pl.dialcom24.p24lib.bank.jshelpers.javascriptinterface { *; } -keep enum pl.dialcom24.p24lib.p24paymentresult$p24paymentresultstatus { *; } Strona 15 z 27

16 Opracował: Arkadiusz 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: %20Owner %20Summary%20Stars 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, 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: Strona 16 z 27

17 Opracował: Arkadiusz 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. 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 ): Strona 17 z 27

18 Opracował: Arkadiusz p24config.merchantid p24config.crc p24payment.sessionid p24payment.amount = 100; p24payment.currency p24payment.clientaddress testowa"; p24payment.clientcity p24payment.clientzipcode p24payment.clientname Kowalski"; p24payment.clientcountry p24payment.clientphone p24payment.language p24payment.client Przykładowa konfiguracja przy wejściu z tokenem transakcji (pkt ): p24payment.token Przykładowa konfiguracja opcjonalna (opisana powyżej): p24payment.method [p24config.enabletestmode: YES]; p24config.storelogindata = YES; p24config.usemobilestyles = NO; p24config.dontaskforsavelogindata = YES; p24config.timelimit = 30; p24config.p24channel = P24_CHANNEL_CARDS; p24payment.p24urlstatus 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 Strona 18 z 27

19 Opracował: Arkadiusz 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]; 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: W wersji 2.0 w bibliotece Windows Phone są niedostępne półautomatyczne formy płatności (e-przelewy). Zostaną one dodane w kolejnej wersji biblioteki. 5.1 Konfiguracja projektu U ustawieniach projektu należy ustawić wersję Windows Phone (Target Windows Phone OS Version). Minimalna wersja Windows Phone, z jaką współpracuje biblioteka, to 8.0. 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, Strona 19 z 27