Zakupy online na fakturę z odroczonym terminem płatności

Transkrypt

1 Zakupy online na fakturę z odroczonym terminem płatności Zasady integracji bramki płatności invipay.com w sklepie internetowym ESR sp. z o.o. (operator platformy invipay.com) 1

2 Podstawowe informacje Stworzyliśmy ten przewodnik, by ułatwić Ci integrację z metodą płatności invipay.com. Pomoże on przejść krok po kroku przez wszystkie punkty konieczne do tego, by aplikacja działała poprawnie. Mamy nadzieję, że w przewodniku znajdziesz odpowiedzi na wszystkie swoje pytania. Jeżeli jednak będziesz potrzebował naszego wsparcia, jesteśmy do Twojej dyspozycji pod adresem pomoc@invipay.com. Zalecamy też zapoznanie się i zastosowanie w Twoim sklepie Zasad promocji zakupów na fakturę z odroczonym terminem płatności, aby osiągnąć najlepsze rezultaty z wprowadzenia tej wygodnej i szybkiej metody płatności. Zakres integracji Integracja z bramką płatności invipay.com jest szybka i prosta. Do wykonania całego procesu płatności potrzeba jedynie 2-3 wywołań naszego API, szczegółowo opisanych w poniższym dokumencie, a resztą zajmujemy się my. 1) Najpierw rejestrujesz chęć płatności za pomocą invipay.com, w odpowiedzi otrzymując informacje niezbędne w dalszych krokach. 2) Twój klient jest przekierowywany do bramki płatności invipay.com, gdzie dokonuje rejestracji i/lub akceptacji płatności, a my wysyłamy do Ciebie status, gdy tylko zakończy ten proces. 3) Ostatnim opcjonalnym krokiem, wykonywanym za pomocą API, jest dosłanie danych wystawionej faktury do zaakceptowanego zamówienia łącznie z jej obrazem w PDF oraz dokonanie potwierdzenia dostawy towaru do Twojego klienta. Krok ten jest niezbędny aby dokonać wypłaty środków z invipay.com i może być wykonany za pomocą API (opisane w niniejszym dokumencie), ręcznie w naszej aplikacji lub za pomocą gotowych integracji z najpopularniejszymi systemami do księgowości online (poznasz je tutaj). Zarejestrowanie nowej transakcji Zaakceptowanie transakcji przez klienta Dołączenie faktury z odroczonym terminem płatności do transakcji w invipay.com ESR sp. z o.o. (operator platformy invipay.com) 2

3 Spis treści Proces obsługi transakcji 1. Zarejestrowanie nowej transakcji w invipay.com Zaakceptowanie transakcji przez klienta Zakończenie transakcji w InviPay.com Aspekty techniczne 4. Sposoby dostępu do API Bezpieczeństwo komunikacji z API Pomoc ESR sp. z o.o. (operator platformy invipay.com) 3

4 1. Zarejestrowanie nowej transakcji w invipay.com Wysłanie żądania rozpoczęcia płatności Zapisanie danych w bazie danych sklepu Zwrócenie danych płatności Gdy Twój klient zdecyduje się na płatność za pośrednictwem invipay.com, zacznij od wysłania do nas żądania rozpoczęcia nowego procesu płatności, wywołując metodę createpayment, do której przekażesz obiekt PaymentCreationData. W ramach tego obiektu możesz podać szereg danych, z których tylko niektóre są wymagane. Zapoznaj się z punktem 4 sposoby dostępu do API, aby dowiedzieć się więcej, na temat wywoływania metod. Dane wymagane: * Kwota brutto transakcji (pricegross) łączna wartość koszyka, która będzie ujęta na fakturze dokumentującej transakcję. * NIP lub Regon klienta (buyergovid) NIP lub Regon Twojego klienta, podany Ci przez klienta w Twoim sklepie. * Numer transakcji (documentnumber) - numer nadany w Twoim systemie, powiązany z tą transakcją (najczęściej numer zamówienia klienta). * URL powrotny (returnurl) - na ten adres przekierujemy Twojego klienta gdy zakończy ścieżkę płatności u nas (logowanie/rejestracja, zatwierdzenie płatności). * URL do raportowania statusu (statusurl) - na ten adres prześlemy do Twojego systemu IT informacje, o statusie transakcji, gdy tylko ten ulegnie zmianie. Na podstawie tej informacji podejmiesz decyzję, jak procedować dalej z transakcją (patrz punkt 2 poniżej - odebranie statusu transakcji). ESR sp. z o.o. (operator platformy invipay.com) 4

5 Dane opcjonalne: * Typ transakcji (isinvoice) Informacja, czy dana transakcja jest zamówieniem (order, wartość pola nie/false) czy od razu udokumentowana jest fakturą sprzedaży (invoice, wartość pola tak/true) - jeżeli pominiesz to pole, uznamy transakcję za zamówienie. * Termin płatności (duedate) - jeżeli transakcja jest od razu udokumentowana fakturą, to musisz podać jej termin płatności. Jeżeli jest to zamówienie to możesz pominąć to pole w tym kroku (patrz punkt 3 - potwierdzenie zakończenia transakcji). * Datę powstania transakcji (issuedate) - możesz podać konkretną datę, jeżeli pominiesz to pole, zostanie mu nadana data momentu rejestracji transakcji w invipay.com (data bieżąca). * Waluta (currency) - kod ISO waluty transakcji, jeżeli pominiesz to pole walutą będzie Polski Złoty (PLN). * Czy transakcja z OBR (norisk) czy transakcja ma być bez objęta opcją braku ryzyka (OBR) - możliwe są trzy wartości: tak (wartość pola: true), nie (wartość pola: false) lub domyślna z ustawień Twojego konta w invipay.com (wartość pola: null). Opcja OBR powoduje, że całe ryzyko nie uregulowania tej transakcji przez Twojego klienta pozostaje po stronie invipay.com. Zaleca się w transakcjach powstałych w e-sklepach aby opcja ta była włączona (wartość pola: true). * klienta (buyer ) - jeżeli go znasz, podaj go nam, wstawimy go od razu do ewentualnego formularza rejestracji, co ułatwi klientowi jego wypełnienie. * Notatka własna (note) - to pole tekstowe jest dla Ciebie do wykorzystania. Jego zawartość zwrócimy Ci zawsze w każdym komunikacie z naszej strony, dotyczącym tej konkretnej transakcji. Możesz tutaj więc przechować swoje dane referencyjne lub inne potrzebne komentarze. * Format wiadomości ze statusem (statusdataformat) - o statusie płatności poinformujemy Cię zawsze, na podany adres url (pole statusurl, patrz punkt 2.). Domyślnie wiadomość od nas będzie w formacie JSON, ale możesz użyć tego pola do zmiany tego formatu na XML, jeżeli tak Ci wygodniej ją obsłużyć. W odpowiedzi na to żądanie dostaniesz odpowiedź jako obiekt typu PaymentStartInfo, a w nim: * Identyfikator płatności (paymentid) - nadany przez nas, unikalny identyfikator tej konkretnej płatności. Będzie Ci on potrzebny do dalszej obsługi płatności, więc koniecznie go zapisz w kontekście transakcji, którą właśnie realizujesz. * Datę wygaśnięcia płatności (timeoutdate) - w tym polu informujemy Cię do której godziny klient ma czas, aby zakończyć płatność po naszej stronie. Po tym terminie płatność zostanie uznana za porzuconą, o czym zostaniesz poinformowany na podany adres URL (statusurl) przekazany nam w żądaniu opisanym powyżej. * Adres przekierowania (redirecturl) - na ten adres przekieruj przeglądarkę swojego klienta (lub wywołaj go w ramach iframe). Pod nim znajdować się będzie nasza bramka płatności, za pomocą której Twój klient opłaci zakupy w Twoim sklepie. ESR sp. z o.o. (operator platformy invipay.com) 5

6 Porada! Jak rozpocząć płatności, odebrać jej dane i przekierować przeglądarkę klienta do bramki płatności invipay.com przy użyciu PHP API SDK? // 1. Zaimportuj odpowiednie klasy biblioteki API require_once(dirname( FILE )."/InviPayApi/PaygateApiClient.class.php"); // 2. Utwórz klienta, podając adres URL oraz klucze API i Signature $client = new PaygateApiClient( $apikey, $signaturekey); // 3. Przygotuj obiekt z danymi nowej płatności $request = new PaymentCreationData(); $request->setreturnurl(" $request->setstatusurl(" $request->setdocumentnumber("test/1/2/3".uniqid()); $request->setissuedate(time() * 1000); // Pamiętaj o mnożeniu $request->setduedate((time() + 60 * 60 * 24 * 7) * 1000); // Pamiętaj o mnożeniu $request->setpricegross(123.00); $request->setnorisk(true); $request->setbuyergovid( '); $request->setbuyer ('test@test.pl'); // 4. Wywołaj metodę createpayment i odbierz jej wynik $result = $client->createpayment($request); // 5. Zapisz sobie identyfikator rozpoczętej płatności $paymentid = $result->getpaymentid(); // 6. Przekieruj przeglądarkę klienta pod wskazany adres header ( Location:. $result-> getredirecturl()); ESR sp. z o.o. (operator platformy invipay.com) 6

7 2. Zaakceptowanie transakcji przez klienta Aby klient mógł dokonać zakupu za pomocą naszej metody płatności musi posiadać konto firmowe w invipay.com. Założenie i prowadzenie takiego konta jest całkowicie bezpłatne. Może je założyć przed przystąpieniem do zakupów lub w ich trakcie z uwagi na to, że cały proces jest internetowy i w pełni zautomatyzowany. Natychmiast po założeniu konta klient otrzymuje od invipay.com zł (limit zakupowy) na swoje zakupy firmowe. Dokonanie autoryzacji zakupów przez klienta w bramce płatności invipay.com sprowadza się już jedynie do zalogowania się na swoim koncie w invipay.com i podania kodu sms wysłanego na telefon komórkowy użytkownika dokonującego zakupów. Cały proces jest online i trwa 40 sekund Jeżeli klient nie posiada konta w invipay.com Podaje dane swojej firmy Przechodzi weryfikację invipay.com Autoryzuje swoje konto za pomocą zwrotnego przelewu na 1 zł Klient loguje się w invipay.com Klient potwierdza swoje zakupy kodem sms Możliwe są trzy scenariusze wyniku przeprocesowania transakcji w bramce płatności invipay.com: a) Klient poprawnie przeszedł proces i potwierdził swoje zakupy. Oznacza to że pieniądze zostały zabezpieczone do wypłaty dla Ciebie przez InviPay.com i możesz natychmiast przystąpić do realizacji zamówienia. b) Klient nie posiada wystarczającego limitu zakupowego w InviPay.com i nie może dokonać zakupów. c) Klient porzucił transakcję lub nie może być klientem invipay.com (zamknął przeglądarkę np. żeby jednak wybrać inną formę płatności lub nie przeszedł procesu zakładania konta w invipay.com). O każdym z ww. wyników powiadomimy Cię, na podany podczas żądania zarejestrowania nowej płatności w invipay.com adres statusurl. W tym kroku istotne jest, że w przypadku punktów a i b klient może (ale nie musi) wrócić do Twojego sklepu. Jeżeli zechce wrócić, przekierujemy jego przeglądarkę na adres, który podałeś w polu returnurl pierwszego zapytania (patrz punkt 1.) ESR sp. z o.o. (operator platformy invipay.com) 7

8 Informujemy o statusie transakcji Zmiana statusu zamówienia w sklepie Zwrócenie statusu transakcji Po każdej zmianie statusu transakcji, zwracamy Ci informację. Wiadomość może być w formacie JSON (domyślnie) lub XML (patrz pole statusdataformat) i będzie niosła następujące dane: * Identyfikator płatności (paymentid) - ten sam identyfikator, który od nas otrzymałeś już w odpowiedzi na pierwsze żądanie rejestracji płatności. Po nim odnajdziesz odpowiednią transakcję w swoim systemie i będziesz mógł ją odpowiednio oznaczyć. * Identyfikator transakcji invipay.com (transactionid) - jeżeli płatność zakończyła się sukcesem, to w tym polu otrzymasz identyfikator transakcji invipay.com. Jest to inny rodzaj obiektu niż obiekt samej płatności i reprezentuje on już konkretną transakcję w aplikacji invipay.com. Możesz tego identyfikatora użyć w innych serwisach naszego API (tutaj odnajdziesz nasze całe API), aby zarządzać tą transakcją w invipay.com. * Informacje o Twoim kliencie (buyer) - podstawowe informacje o Twoim kliencie takie jak nazwa (name), numer NIP (taxpayernumber), REGON (companygovid), ( ), fax (fax), telefon (phone), strona WWW (www), dane konta bankowego (account) czy adres siedziby (address). * Datę rozpoczęcia procesu płatności (created) data wysłania żądania utworzenia nowej transakcji do invipay.com. * Datę wygaśnięcia płatności (timeoutdate) - w tym polu informujemy Cię, do której godziny klient ma czas, aby zakończyć płatność w naszej bramce. Po tym terminie płatność zostanie uznana za porzuconą, o czym zostaniesz poinformowany na podany adres URL (statusurl) przekazany nam w żądaniu opisanym powyżej. * Twoją notatkę (note) wartość, którą mogłeś podać w żądaniu rozpoczęcia transakcji. Pole do Twojej dyspozycji. * Status płatności (status) - najważniejsze pole, informuje jak jest obecny status tej transakcji. Możliwe wartości to: * STARTED - klient jeszcze nie zatwierdził płatności w naszej bramce. Tego statusu nie otrzymasz nigdy automatycznie, ale możesz go napotkać, gdy ręcznie odpytasz nasze API o płatność (patrz niżej). ESR sp. z o.o. (operator platformy invipay.com) 8

9 * OUT_OF_LIMIT - klient niestety nie mógł dokończyć zakupów ponieważ jego limit zakupowy w invipay.com był niewystarczający. * TIMEDOUT - klient prawdopodobnie porzucił transakcję, nie mógł być klientem invipay.com lub upłynął czas na dokonanie potwierdzenia transakcji w naszej bramce (powiadomiliśmy Cię w polu timeoutdate). * COMPLETED - klient potwierdził swoje zakupy i można realizować zlecenie klienta. Sama transakcja czeka w InviPay.com na jej zakończenie (wystawienie faktury i potwierdzenie dostawy towaru/usługi do klienta) - (patrz poniżej na punkt 3.) Powyższe informacje otrzymasz automatycznie, na podany przez Siebie (w polu statusurl) adres. Możesz też w każdej chwili je uzyskać, ręcznie odpytując nasze API, podając do metody getpayment identyfikator płatności otrzymany w odpowiedzi na rejestrację nowej płatności. Uwaga! Nie należy odpytywać cyklicznie tej metody, w celu aktualizacji statusu po stronie swojego systemu IT. invipay.com zawsze prześlę Ci te dane w momencie zmiany statusu. Metoda getpayment ma za zadanie umożliwienie pozaplanowego pobrania tych informacji, w szczególnych przypadkach. Porada! Jak odebrać statusu transakcji, przy użyciu API SDK PHP? // 1. Zaimportuj odpowiednie klasy biblioteki API require_once(dirname( FILE )."/InviPayApi/PaygateApiClient.class.php"); // 2. Utwórz klienta, podając adres URL oraz klucze API i Signature $client = new PaygateApiClient( $apikey, $signaturekey); // 3. Wywołaj API, aby z danych wywołania utworzyło obiekt PaymentData: $paymentdata = $client->paymentstatusfromcallbackpost(callbackdataformat::json); // 4. Zależnie od statusu płatności możesz zdecydować, jak postąpić dalej z tym koszykiem: $paymentid = $paymentdata->getpaymentid(); $paymentstatus = $paymentdata->getstatus(); ESR sp. z o.o. (operator platformy invipay.com) 9

10 3. Zakończenie transakcji w InviPay.com Całkowite zamknięcie transakcji w invipay.com odbywa się po dostarczeniu zamówienia do klienta i wystawieniu faktury z odroczonym terminem płatności (jeżeli nie była wystawiona wcześniej). Taką fakturę należy dołączyć do otwartej transakcji w invipay.com i zawiadomić invipay.com o dostarczeniu towaru do klienta. Następnie, pozostaje już tylko wypłacić swoje wynagrodzenie z invipay.com. Dołączyć fakturę do zamówienia można ręcznie, za pomocą API (opisane poniżej) lub gotowych integracji Dostawa zamówienia do klienta Przekazanie danych o dostarczeniu przesyłki od kuriera do sklepu Wystawienie i dołączenie faktury z odroczonym terminem płatności do transakcji w invipay.com Wypłata środków z invipay.com Po otrzymaniu od nas statusu COMPLETED (patrz punkt 2) pozostaje ostatni krok do wykonania, po Twojej stronie - uzupełnienie danych faktury oraz potwierdzenie dostarczenia towaru. Jeżeli chcesz to wykonać za pomocą API służy do tego jedna metoda managepayment, przyjmująca obiekt typu PaymentManagementData. Transakcja typu Order (zamówienie) Jeżeli transakcja ma postać zamówienia (order), czyli została założona (patrz punkt 1) z polem isinvoice ustawionym na domyślną wartość false, to musimy ją ostatecznie przekonwertować na fakturę (invoice). W tym celu, w ramach tego zapytania musisz: a) załączyć elektroniczny dokument z fakturą. Służy do tego pole document, które jest typu FileData i przyjmuje następujące dane: * name - nazwa pliku * mimetype - typ mime pliku (np. application/pdf, text/plan itd.) ESR sp. z o.o. (operator platformy invipay.com) 10

11 * content - binarna zawartość pliku skonwertowana do ciągu tekstowego za pomocą algorytmu base64 b) uzupełnić wymagane dane, używając pola conversiondata typu OrderToInvoiceData, w którym podajesz: * invoicedocumentnumber - numer dokumentu faktury * issuedate - datę wystawienia faktury * duedate - datę wymagalności faktury Transakcja typu Invoice (faktura) Jeżeli transakcja była fakturą od początku, czyli została założona (patrz punkt 1) z polem isinvoice ustawionym na wartość true, wystarczy jak doślesz nam elektroniczny dokument tej faktury, wypełniając jedynie pole document, które jest typu FileData i przyjmuje następujące dane: * name - nazwa pliku * mimetype - typ mime pliku (np. application/pdf, text/plan itd.) * content - binarna zawartość pliku skonwertowana do ciągu tekstowego za pomocą algorytmu base64 Potwierdzenie dostawy towaru do klienta Po wykonaniu powyższego, możesz potwierdzić nam dostawę towaru, co przeniesie transakcję do Twojego portfela invipay.com i będziesz mógł wypłacić środki. Aby to zrobić, ustaw po prostu pole doconfirmdelivery na wartość tak (true). Możesz to zrobić w ramach tego samego żądania lub wywołując metodę managepayment ponownie, tym razem już bez wypełniania pól document czy conversiondata. Poniższe przykłady pomogą Ci przejść gładko przez ten krok. Porada! Jak dokonać konwersji zamówienia do faktury, przy pomocy API SDK PHP? // 1. Zaimportuj odpowiednie klasy biblioteki API require_once(dirname( FILE )."/InviPayApi/PaygateApiClient.class.php"); // 2. Utwórz klienta, podając adres URL oraz klucze API i Signature $client = new PaygateApiClient( $apikey, $signaturekey); // 3. Utwórz obiekt danych wejściowych i ustaw pole doconfirmdelivery na true $request = new PaymentManagementData(); $request->setpaymentid($paymentid); // Podaj tutaj identyfikator płatności, otrzymany od nas w obiekcie PaymentStartInfo // 4. Utwórz obiekt dokumentu $document = new FileData(); // 4a. Użyj tej metody, aby SDK samodzielnie ustaliło typ pliku, jego nazwę oraz skonwertowało binarną zawartość pliku do ciągu tekstowego Base64 $document->setfromfile(dirname( FILE ).'/data/test.pdf'); ESR sp. z o.o. (operator platformy invipay.com) 11

12 // 4b. Dodaj dokument, do obiektu żądania $request->setdocument($document); // 5. Utwórz obiekt konwersji $conversiondata = new OrderToInvoiceData(); // 5b. Wypełnij prawdziwymi danymi, pamiętaj aby znaczniki czasu pomnożyć przez 1000 $conversiondata->setinvoicedocumentnumber("testinvoice/1/2/3/".uniqid()); $conversiondata->setissuedate(time() * 1000); $conversiondata->setduedate((time() + 60 * 60 * 24 * 7) * 1000); // 5b. Dodaj dane konwersji, do obiektu żądania $request->setconversiondata($conversiondata); // 6. Wywołaj metodę managepayment $result = $client->managepayment($request); Porada! Jak dodać dokument do danych faktury, przy pomocy API SDK PHP? // 1. Zaimportuj odpowiednie klasy biblioteki API require_once(dirname( FILE )."/InviPayApi/PaygateApiClient.class.php"); // 2. Utwórz klienta, podając adres URL oraz klucze API i Signature $client = new PaygateApiClient( $apikey, $signaturekey); // 3. Utwórz obiekt danych wejściowych i ustaw pole doconfirmdelivery na true $request = new PaymentManagementData(); $request->setpaymentid($paymentid); // Podaj tutaj identyfikator płatności, otrzymany od nas w obiekcie PaymentStartInfo // 4. Utwórz obiekt dokumentu $document = new FileData(); // 4a. Użyj tej metody, aby SDK samodzielnie ustaliło typ pliku, jego nazwę oraz skonwertowało binarną zawartość pliku do ciągu tekstowego Base64 $document->setfromfile(dirname( FILE ).'/data/test.pdf'); // 4b. Dodaj dokument do obiektu żądania $request->setdocument($document); // 5. Wywołaj metodę managepayment $result = $client->managepayment($request); ESR sp. z o.o. (operator platformy invipay.com) 12

13 Porada! Jak powiadomić invipay.com o dostawie towaru, przy pomocy API SDK PHP? // 1. Zaimportuj odpowiednie klasy biblioteki API require_once(dirname( FILE )."/InviPayApi/PaygateApiClient.class.php"); // 2. Utwórz klienta, podając adres URL oraz klucze API i Signature $client = new PaygateApiClient( $apikey, $signaturekey); // 3. Utwórz obiekt danych wejściowych i ustaw pole doconfirmdelivery na true $request = new PaymentManagementData(); $request->setpaymentid($paymentid); // Podaj tutaj identyfikator płatności, otrzymany od nas w obiekcie PaymentStartInfo $request->setdoconfirmdelivery(true); // 4. Wywołaj metodę managepayment $result = $client->managepayment($request); Porada! Jak powiadomić invipay.com o dostawie towaru przy okazji innej wiadomości? Pamiętaj, że możesz wykonać potwierdzenie dostawy towaru oraz np. skonwertować zamówienie do faktury lub dodać dokument do faktury, w ramach jednego wywołania metody managepayment. Wystarczy, że pole doconfirmdelivery ustawisz na wartość true. ESR sp. z o.o. (operator platformy invipay.com) 13

14 4. Sposoby dostępu do API Dla Twojej wygody przygotowaliśmy dostęp do API invipay.com dwoma najpopularniejszymi metodami. SOAP Jeżeli Twój system IT jest stworzony w języku z silnym typowaniem zmiennych (np. C#, Java), zalecamy wykorzystanie technologii SOAP, gdyż umożliwi Ci to łatwe wygenerowanie wszystkich niezbędnych danych i obiektów, a także późniejsze aktualizacje i rozwinięcia. Pamiętaj jednak, o konieczności oprogramowania obsługi podpisów wiadomości, opisanych w punkcie 5. Aby automatycznie wygenerować klienta bramki płatniczej invipay.com oraz wszystkie obiekty przenoszenia danych, zajrzyj do dokumentacji technicznej Twojego środowiska programistycznego, gdzie znajdziesz informacje, o tym jak to zrobić. Dokument WSDL znajdziesz pod adresem: REST Jeżeli Twój system IT został stworzony w oparciu o PHP, zalecamy użycie naszego API SDK, które zawiera pełnego klienta REST dla PHP. Link do SDK znajdziesz w sekcji 6. Poniżej. Jeżeli jednak chcesz wykorzystać REST samodzielnie, lub Twój system IT został stworzony w innej technologii, a nie chcesz korzystać z protokołu SOAP, poniżej znajdziesz zestawienie metod, adresów URL i obiektów przenoszenia danych, niezbędnych do pełnej komunikacji. W niniejszej dokumentacji omawialiśmy kolejne kroki działania bramki płatności, odwołując się do metod API po ich nazwie. Np. wywołaj metodę createpayment. Są to nazwy metod zgodne z protokołem SOAP oraz klientem PHP z naszego SDK. Jeżeli chcesz je wywoływać samodzielnie, w ramach komunikacji protokołem REST, będziesz potrzebować ich docelowego adresu URL, metody HTTP i typów danych wejściowych i wyjściowych. Zestawienie tych informacji znajdziesz w tabeli poniżej. Zajrzyj też do sekcji Obiekty wymiany danych. Uwaga! Pamiętaj, o konieczności oprogramowania obsługi podpisów wiadomości, opisanych w punkcie 5. Metody REST i ich adresy URL: Nazwa metody URL Typ danych wejściowych Typ danych wyjściowych createpayment POST PaymentCreationData PaymentStartInfo ate getpayment GET String PaymentData ails managepayment nage POST PaymentManagementData PaymentData ESR sp. z o.o. (operator platformy invipay.com) 14

15 Obiekty wymiany danych PaymentCreationData Uwaga na daty! W przypadku protokołu REST należy pamiętać, że wszystkie daty (np. data wystawienia faktury, data wymagalności itd.) należy podawać i są podawane jako UNIXowy znacznik czasu w mikrosekundach (tysięczne części sekundy). Oznacza to, że może wystąpić (np. w przypadku PHP i jego metody time()) konieczność przemnożenia znacznika czasu przez 1000, przy podawaniu go do serwisu API, oraz podzielenia go przez 1000, przy odbieraniu daty z serwisu API. Sprawdź koniecznie, w dokumentacji swojego języka programowania, czy znaczniki czasu są podawane jako liczba sekund czy mikrosekund, jakie upłynęły od 1 stycznia 1970 roku. Nazwa pola Typ danych Opis Wymagane? returnurl String Adres powrotny do Twojego sklepu T statusurl String Adres, na który otrzymasz informację o zmianie statusu płatności T statusdataformat String Wartości: JSON lub XML w jakim formacie danych przesłać Ci status płatności, domyślnie JSON documentnumber String Numer zamówienia T issuedate Timestamp Data wystawienia zamówienia duedate Timestamp Termin płatności faktury T jeżeli invoice pricegross Liczba Łączna kwota brutto zamówienia currency String Kod ISO waluty, domyślnie PLN buyergovid String NIP lub Regon klienta T buyer String Adres klienta note String Pole do Twojej dyspozycji norisk Boolean Czy transakcja ma być z OBR (true), bez OBR (false) czy zgodnie z ustawieniem konta (null) isinvoice Boolean Czy płatność od razu dotyczy faktury (true) czy zamówienia (false, domyślnie) PaymentStartInfo Nazwa pola Typ danych Opis paymentid String Identyfikator właśnie utworzonej płatności redirecturl String Na ten adres przekieruj przeglądarkę klienta, aby przeszedł do naszej bramki timeoutdate Timestamp Data, po której płatność zostanie przeterminowana, jeżeli klient jej nie dokończy PaymentManagementData Nazwa pola Typ danych Opis Wymagane? paymentid String Identyfikator płatności, otrzymany w obiekcie T PaymentStartInfo conversiondata OrderToInvoiceData Jeżeli płatność dotyczyła zamówienia, musisz ją przekonwertować ostatecznie do faktury, wypełnij te dane. document FileData Dokument faktury (np. PDF) doconfirmdelivery Boolean Ustaw na true, jeżeli potwierdzasz dostawę towaru do klienta ESR sp. z o.o. (operator platformy invipay.com) 15

16 OrderToInvoiceData Nazwa pola Typ danych Opis Wymagane? invoicedocumentnumber String Numer dokumentu faktury T issuedate Timestamp Data wystawienia faktury T duedate Timestamp Termin płatności faktury T FileData Nazwa pola Typ danych Opis Wymagane? name String Nazwa pliku T mimetype String Typ pliku, domyślnie application/pdf content Base64 Binarna zawartość pliku, zakodowana algorytmem Base64 do typu danych String T PaymentData Nazwa pola Typ danych Opis paymentid String Identyfikator płatności, otrzymany w obiekcie PaymentStartInfo transactionid String Identyfikator transakcji, powstałej w wyniku tej płatności buyer Contractor Dane kupującego created Timestamp Data utworzenia timeoutdate Timestamp Data ewentualnego przeterminowania status String Status płatności (patrz punkt 2 informujemy o statusie transakcji), możliwe wartości: STARTED, COMPLETED, OUT_OF_LIMIT, TIMEDOUT note String Dowolne Twoje dane, podane podczas zakładania tej płatności Contractor Nazwa pola Typ danych Opis name String Nazwa firmy taxpayernumber String NIP companygovid String REGON String Adres fax String Numer faksu phone String Numer telefonu WWW String Adres strony WWW account BankAccount Informacje, o koncie bankowym address Address Adres siedziby BankAccount Nazwa pola Typ danych Opis bankname String Nazwa banku number String Numer konta Address Nazwa pola Typ danych Opis street String Ulica, wraz z numerem budynku i lokalu city String Miasto postcode String Kod pocztowy countrycode String Kod ISO kraju ESR sp. z o.o. (operator platformy invipay.com) 16

17 5. Bezpieczeństwo komunikacji z API Dołożyliśmy wszelkich starań, aby nasza komunikacja przebiegała w bezpieczny sposób. Dlatego, aby skorzystać z naszego API będziesz potrzebować dwóch kluczy dostępowych: publicznego i prywatnego. Znajdziesz je w Ustawieniach aplikacji invipay.com w sekcji Integracje. Jeżeli używasz SDK PHP Jeżeli używasz naszego SDK, wystarczy, że podasz oba klucze w konstruktorze klienta bramki płatniczej, tak jak na poniższym przykładzie: Porada! Jak przekazać klucze API do klienta API SDK PHP? new PaygateApiClient(URL_API_INVIPAY, KLUCZ_PUBLICZNY, KLUCZ_PRYWATNY); Jeżeli nie używasz SDK PHP Klucz publiczny służy za identyfikator Twojego konta w aplikacji invipay.com. Za jego pomocą rozpoznajemy jaki system się z nami komunikuje. Niezależnie od metody dostępu, czy SOAP czy REST, klucz publiczny należy przesłać wraz z każdą wiadomością w nagłówku HTTP, o nazwie X-InviPay-ApiKey. Klucz prywatny służy do podpisywania wiadomości. Nie należy go nigdy przesyłać w jakikolwiek sposób! Podpisanie wiadomości stanowi w pewnym sensie rodzaj hasła (wiemy, że znasz klucz prywatny, bo podpis się zgadza) oraz dodatkowo (poza warstwą SSL) zapewnia, że nikt po drodze nie zmienił Twojego żądania lub naszej odpowiedzi. Podpis wiadomości tworzy się poprzez złączenie ciągu znaków tworzących tą wiadomość (w przypadku REST będzie to JSON wyjściowy, w przypadku SOAP cały XML wyjściowy) oraz klucza prywatnego, bez jakichkolwiek separatorów, a następnie utworzenie skrótu tak powstałego ciągu znaków, za pomocą algorytmu SHA-256. Tak powstały skrót zapisujemy w postaci hexadecymalnej (małe litery) i przesyłamy wraz z wiadomością w nagłówku HTTP, o nazwie X-InviPay-Signature. ESR sp. z o.o. (operator platformy invipay.com) 17

18 Wiadomość Klucz prywatny SHA256 Klucz publiczny X-InviPay-Signature -... X-InviPay-ApiKey - Przykład. Jak zabezpieczyć poprawnie wiadomość? 1) Wysyłasz do metody create żądanie rozpoczęcia nowej transakcji, a więc JSON, który ma mniej-więcej taką postać: {"returnurl": " "statusurl: " "documentnumber": "Order/66", "pricegross": , "buyergovid": } Twój prywatny klucz do API to powiedzmy: ABCD-ABCD-ABCD-ABCD-ABCD. 2) Łączymy więc oba ciągi znaków w jeden i wykonujemy skrót SHA-256: String dopodpisu = { "returnurl": " "statusurl: " "documentnumber": "Order/66", "pricegross": , "buyergovid": } + ABCD-ABCD-ABCD-ABCD-ABCD ; String podpis = sha256hex(dopodpisu); 3) I otrzymujesz wartość zmiennej podpis, która w tym przypadku będzie miała postać: 13e4763bf1489d500d22f2e10fe009d66ad6a999458e99f344e815fa133339d2 i którą wysyłasz do nas w nagłówku HTTP X-InviPay-Signature. Podpis działa w obie strony każdej odpowiedzi naszego API zawsze towarzyszy również nagłówek HTTP X-InviPay-Signature, a w nim znajduje się podpis treści odpowiedzi, wykonany zgodnie z przedstawionymi powyżej zasadami. Zachęcamy do wykorzystania tego podpisu, w celu weryfikacji integralności naszej wiadomości. ESR sp. z o.o. (operator platformy invipay.com) 18

19 6. Pomoc Nasz zespół techniczny z przyjemnością pomoże w pomyślnej integracji Twojego biznesu z bramką InviPay.com. Dostęp do naszego całego API znajdziesz tutaj Nasze SDK PHP znajdziesz tutaj W razie problemów lub pytań pomoc@invipay.com lub zadzwoń do nas, jeżeli taki kontakt wolisz ESR sp. z o.o. (operator platformy invipay.com) 19