Dokumentacja techniczna 1.0 Płatności CashBill - SOAP Dokumentacja wdrożenia systemu Płatności CashBill w oparciu o komunikację według protokołu SOAP CashBill Spółka Akcyjna ul. Rejtana 20, 41-300 Dąbrowa Górnicza Tel.: +48 032 764-18-42 Fax: +48 032 764-18-40 Infolinia: 0 801 011 802 e-mail: marketing@cashbill.pl NIP: 629-241-08-01 KRS: 0000323297 REGON: 241048572 kapitał zakładowy 5 000 000 zł opłacony w całości
Spis treści 1 Zgłoszenie uruchomienia usługi...3 2 Proces przeprowadzenia płatności...3 3 Statusy transakcji... 4 4 Usługa powiadamiania (Notification service)...4 4.1 Dostępne komunikaty... 5 5 Usługa zarządzania sesjami (SOAP)...6 5.1 Operacja opensession... 6 5.2 Operacja closesession... 7 5.3 Operacja forwardfor... 7 6 Usługa zarządzania operatorami płatności (SOAP)...8 6.1 Operacja availablepaymentchannels...8 6.2 Operacja starttransaction... 9 7 Usługa zarządzania transakcjami...10 7.1 Operacja getdetails... 11 8 Historia zmian... 12 2
1 Zgłoszenie uruchomienia usługi W celu uruchomienia usługi należy określić: adres ip komputera, z którego wykonywane będą połączenia do usług systemu NeoPAY; adres URL, na który będą wysyłane komunikaty z systemu NeoPAY; Po otrzymaniu tych danych zostanie wygenerowany i przesłany identyfikator sklepu oraz tajny klucz, który posłuży do autoryzacji wszelkich operacji wykonywanych przez sklep. 2 Proces przeprowadzenia płatności Poniższy diagram przedstawia pełny proces przeprowadzenia transakcji przy pomocy systemu NeoPAY. Linie ciągłe oznaczają komunikację przy pomocy kanału serwer serwer, przerywane to droga przeglądarki klienta. Etykiety nad liniami określają rodzaj operacji przeprowadzanej przy pomocy protokołu SOAP. Proces przeprowadzenia płatności 3
3 Statusy transakcji Każda z transakcji posiada status określający jej stan w procesie jej obsługi. Możliwe statusy transakcji to: Status Start NegativeAuthorization Abort Fraud PositiveAuthorization PositiveFinish Opis Transakcja zostało rozpoczęta, klient nie dokonał jeszcze płatności. Operator płatności nie autoryzował transakcji, status jest ostateczny i nie może ulec zmianie. Klient zrezygnował z dokonania płatności, status jest ostateczny i nie może ulec zmianie. Operator płatności określił transakcje jako próbę wyłudzenia, jej realizacja zostaje wstrzymana. Status jest ostateczny i nie może ulec zmianie. Transakcja została wstępnie pozytywnie autoryzowana przez operatora płatności, jej ostateczny status zostanie określony w późniejszym okresie. Operator płatności ostatecznie pozytywnie potwierdził poprawność przeprowadzonej transakcji, status jest ostateczny i nie może ulec zmianie. Tabela 1: Statusy transakcji 4 Usługa powiadamiania (Notification service) System NeoPAY komunikuje się z systemem sklepu przy pomocy usługi powiadamiania. Adres URL, na którym została ona uruchomiona po stronie sklepu musi zostać określony podczas zgłoszenia uruchomienia usługi i jest niezmienny dla każdej transakcji (w przeciwieństwie do adresów URL powrotu przeglądarki klienta). Komunikacja z systemem sklepu odbywa się przy pomocy protokołu http. Jako, że dane, które są przesyłane w procesie komunikacji nie są wrażliwe nie jest wymagane stosowanie ich szyfrowania (jak ma to miejsce w przypadku komunikacji w przeciwną stronę: sklep Pojedyncze powiadomienie składa się z: system NeoPAY). nazwy komunikatu atrybutów komunikatu Usługa powiadamiania (Notification service) 4
podpisu pozwalającego sprawdzić wiarygodność komunikatu Komunikat zostaje wysłany do systemu sklepu jako żądanie GET, składa się z następujących zmiennych: Zmienna cmd args sign Opis nazwa komunikatu; atrybuty komunikatu przedzielone znakiem ',' (przecinek); podpis wykonany przy pomocy funkcji podpisującej (patrz niżej) Funkcja podpisująca sign = md5(cmd + arg + tajnyklucz) md5 jest funkcją skrótu MD5, tajnyklucz to klucz nadany w procesie zgłoszenia uruchomienia usługi, + to operacja konkatenacji napisów. 4.1 Dostępne komunikaty Komunikat transactionstatuschanged Opis Komunikat wysyłany w przypadku zmiany statusu transakcji. Jedyny argument jaki przekazuje to identyfikator transakcji. Po poprawnym odebraniu komunikatu sklep winien odpowiedzieć wystawiając na wyjście ciąg znaków w postaci: OK Każda inna odpowiedź zostanie zinterpretowana jako wystąpienie błędu w czasie odbioru komunikatu. W takim przypadku komunikat zostanie wysłany ponownie, aż do uzyskania poprawnego potwierdzenia. Usługa powiadamiania (Notification service) 5
Przykładowy komunikat http://adres_sklepu/kom.html?cmd=transactionstatuschanged& args=asd34sf&sign=c8143d45bf2f76fd38a6a9d77feb1a79 5 Usługa zarządzania sesjami (SOAP) Usługa pozwala na rozpoczęcie sesji w systemie Płatności CashBill. WSDL dla tej usługi jest dostępny pod adresem URL: https://pay.cashbill.pl/soap/session/?wsdl 5.1 Operacja opensession Żądanie rozpoczęcia autoryzowanej sesji z dowolną usługą systemu Neopay. Każda autoryzowana operacja wymaga przekazania zwróconego przez opensession identyfikatora sesji za pomocą dołączenia odpowieniego nagłówka (opis niżej). Sesja jest otwarta do czasu jej zamknięcia przy pomocy operacji closesession lub w przypadku wykrycia próby jej przejęcia (np. przez wysłanie komunikatu z poprawnym identyfikatorem sesji ale z innego adresu ip niż została wykonana operacja opensession). Zaleca się otwierać nową sesję dla każdego ciągu logicznie powiązanych operacji (np. odpytanie o dostępne kanały płatności i następnie wykonacie operacji rozpoczęcia transakcji). komunikat wejściowy opensessionrequest shopid shopidtype 1 Unikalny identyfikator sklepu nadany w procesie rejestracji secretphrase secretphrase 1 Tajny klucz sklepu nadany w procesie rejestracji Usługa zarządzania sesjami (SOAP) 6
komunikat wyjściowy opensessionresponse opensessionresponse sessionidtype 1 Identyfikator sesji używany do autentykacji kolejnych żądań wysyłanych do usług systemu Płatności CashBill 5.2 Operacja closesession Zakończnie otwartej sesji. Zaleca się wykonanie operacji zamknięcia sesji po każdym zakończeniu ciągu logicznie powiązanych operacji. Nagłówek wejściowy validatesessionrequestheader validatesession sessionidtype 1 Identyfikator sesji nadany w procesie autoryzacji 5.3 Operacja forwardfor Uruchomienie trybu przekazywania dalej (wymagany sklep działający w trybie FORWARDER). W trybie tym sklep może wykonywać wszelkie operacje jakby był sklepem o innym identyfikatorze. Jeden sklep działający w trybie FORWARDED może mieć przypisany szereg sklepów, dla których wykonuje operację przekazywania dalej. Nagłówek wejściowy validatesessionrequestheader validatesession sessionidtype 1 Identyfikator sesji nadany w procesie autoryzacji Komunikat wejściowy forwardfor forwardfor shopidtype 1 Identyfikator sklepu, którego żądania mają być przekazywane przez sklep główny (tylko dla sklepów działających w trybie FORWARDER) Usługa zarządzania sesjami (SOAP) 7
6 Usługa zarządzania operatorami płatności (SOAP) Usługa udostępnia operacje pozwalające na dostęp do opisów i właściwości operatorów płatności oraz na rozpoczęcie transakcji. WSDL dla tej usługi jest dostępny pod adresem URL: https://pay.cashbill.pl/soap/paymentchannel?wsdl 6.1 Operacja availablepaymentchannels Pobranie dostępnych dla danego sklepu kanałów płatności. Lista kanałów płatności może się zmieniać w czasie działania systemu dlatego zaleca się wykonanie operacji availablepaymentchannels przed każdym zaprezentowaniem klientowi listy dostępnych kanałów płatności. Każdy kanał płatności posiada status (może się on zmieniać w czasie działana systemu). Określa on aktualną dostępność kanału płatności. Dostępne statusy to: Status AVAILABLE AVAILABLE_ONLINE DISABLED Opis Kanał dostępny, autoryzacja płatności tym kanałem może zostać odroczona w czasie o maksymalnie jeden dzień roboczy od momentu jej prawidłowego autoryzowania przez operatora płatności. Kanał dostępny w trybie umożliwiającym wykonanie natychmiastowej płatności. Czas oczekiwania na autoryzację płatności wynosi kilka minut. Kanał niedostępny (nie umożliwia aktualnie rozpoczęcia płatności). Kanał o takim statusie może być prezentowany klientowi końcowemu, jednak z zaznaczeniem, że jest on chwilowo niedostępny. Tabela 2: Statusy dostępności kanału płatności Nagłówek wejściowy validatesessionrequestheader validatesession sessionidtype 1 Identyfikator sesji nadany w procesie autoryzacji Usługa zarządzania operatorami płatności (SOAP) 8
Komunikat wyjściowy availablepaymentchannelsresponse id paymentchannelidtype 1 Identyfikator kanału płatności type xsd:token 1 Typ kanału płatności (patrz niżej) status xsd:token 1 Aktualny status kanału płatności group xsd:token 0..1 Grupa logiczna, do której należy kanał płatności currency ISOCodeType 1..* Lista dostępnych walut details paymentchanneldetailstype 1..* Lista zawierająca szczegóły dotyczące kanału płatności w różnych językach Typ CREDIT_CARD Opis Karty kredytowe INSTANT_PAYMENT Płatności dokonywane w trybie natychmiastowym BANK_TRANSFER OTHER Nieautomatyczne przelewy bankowe Inne kanały płatności nie należące do grup przedstawionych powyżej (np. testowy kanał płatności) Tabela 3: Typy kanłów płatności 6.2 Operacja starttransaction Rozpoczęcie transakcji dla danego kanału płatności. Adresy URL powrotu przeglądarki klienta ustalają adres, na który zostanie przekierowana przeglądarka klienta po zakończeniu procesu płatności, jest on zależny od statusu zakończenia transakcji. Adresy te są wymagane dla każdej transakcji. Nagłówek wejściowy validatesessionrequestheader validatesession sessionidtype 1 Identyfikator sesji nadany w procesie autoryzacji Usługa zarządzania operatorami płatności (SOAP) 9
Komunikat wejściowy starttransactionrequest paymentchannelid paymentchannelidtype 1 Identyfikator kanału płatności otrzymany po wykonaniu żądania availablepaymentchannels title xsd:string 1 Tytuł transakcji description xsd:string 0..1 Opis transakcji amount amounttype 1 Kwota transakcji positiveurl httpurl 1 negativeurl httpurl 1 Adres powrotu przeglądarki klienta po pozytywnym zakończeniu transakcji Adres powrotu przeglądarki klienta po negatywnym zakończeniu transakcji clientdata clientdatatype 0..1 Dodatkowe dane opisujące klienta Komunikat wyjściowy: starttransactionresponse id transactionid 1 Identyfikator rozpoczętej transakcji form formtype 1 Parametry formularza przekazującego klienta do operatora płatności 7 Usługa zarządzania transakcjami Usługa udostępnia operacje związane z zarządzaniem transakcjami, tj. pobranie informacji dotyczących szczegółów transakcji np. w celu jej weryfikacji. WSDL dla tej usługi jest dostępny pod adresem URL: https://pay.cashbill.pl/soap/transaction?wsdl Usługa zarządzania transakcjami 10
7.1 Operacja getdetails Pobranie informacji dotyczących transakcji o zadanym identyfikatorze Nagłówek wejściowy: validatesessionrequestheader validatesession sessionidtype 1 Identyfikator sesji nadany w procesie autoryzacji Komunikat wejściowy: getdetails getdetails TransactionId 1 Identyfikator transakcji Komunikat wyjściowy: getdetailsresponse id transactionid 1 Identyfikator transakcji amount amounttype 1 Kwota transakcji title xsd:string 1 Tytuł transakcji description xsd:string 1 Opis transakcji status statustype 1 Aktualny status transakcji paymentchannel paymentchannelidtype 1 Kanał płatności, przy pomocy którego została wykonana transakcja time xsd:datetime 1 Data rozpoczęcia transakcji Usługa zarządzania transakcjami 11
8 Historia zmian data zmiany 16.11.2012 Nowa wersja dokumentacji Historia zmian 12