Płatności CashBill

Transkrypt

Płatności CashBill

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: [email protected]
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
Opis
Start
Transakcja zostało rozpoczęta, klient nie dokonał
jeszcze płatności.
NegativeAuthorization
Operator płatności nie autoryzował transakcji, status
jest ostateczny i nie może ulec zmianie.
Abort
Klient zrezygnował z dokonania płatności, status jest
ostateczny i nie może ulec zmianie.
Fraud
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.
PositiveAuthorization
Transakcja została wstępnie pozytywnie autoryzowana
przez operatora płatności, jej ostateczny status
zostanie określony w późniejszym okresie.
PositiveFinish
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 → system NeoPAY).
Pojedyncze powiadomienie składa się z:
 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
Opis
cmd
nazwa komunikatu;
args
atrybuty komunikatu przedzielone znakiem ',' (przecinek);
sign
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
Opis
transactionStatusChanged
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
Pole
Typ
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)
Rozmiar Opis
6
 komunikat wyjściowy openSessionResponse
Pole
Typ
openSessionResponse
sessionIdType
Rozmiar Opis
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
Pole
Typ
validateSession
sessionIdType
Rozmiar Opis
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”.
Pole
Typ
validateSession
sessionIdType
Rozmiar Opis
1
 Komunikat wejściowy forwardFor
Pole
Typ
forwardFor
shopIdType
Usługa zarządzania sesjami (SOAP)
Rozmiar Opis
1
Identyfikator sklepu, którego żądania mają być
przekazywane przez sklep główny (tylko dla
sklepów działających w trybie FORWARDER)
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
Opis
AVAILABLE
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.
AVAILABLE_ONLINE
Kanał dostępny w trybie umożliwiającym wykonanie natychmiastowej płatności.
Czas oczekiwania na autoryzację płatności wynosi kilka minut.
DISABLED
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
Pole
Typ
validateSession
sessionIdType
Rozmiar Opis
1
Usługa zarządzania operatorami płatności (SOAP)
8
 Komunikat wyjściowy availablePaymentChannelsResponse
Pole
Typ
Rozmiar Opis
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
Opis
CREDIT_CARD
Karty kredytowe
INSTANT_PAYMENT Płatności dokonywane w trybie natychmiastowym
BANK_TRANSFER
Nieautomatyczne przelewy bankowe
OTHER
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.
Pole
Typ
validateSession
sessionIdType
Rozmiar Opis
1
Usługa zarządzania operatorami płatności (SOAP)
9
 Komunikat wejściowy startTransactionRequest
Pole
Typ
Rozmiar Opis
paymentChannelId
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
Adres powrotu przeglądarki klienta po
pozytywnym zakończeniu transakcji
negativeURL
httpURL
1
Adres powrotu przeglądarki klienta po
negatywnym zakończeniu transakcji
clientData
clientDataType
0..1
Dodatkowe dane opisujące klienta
 Komunikat wyjściowy: startTransactionResponse
Pole
Typ
Rozmiar Opis
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
Pole
Typ
validateSession
sessionIdType
Rozmiar Opis
1
 Komunikat wejściowy: getDetails
Pole
Typ
getDetails
TransactionId
Rozmiar Opis
1
Identyfikator transakcji
 Komunikat wyjściowy: getDetailsResponse
Pole
Typ
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
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
Rozmiar Opis
11
8 Historia zmian
data
zmiany
16.11.2012
Nowa wersja dokumentacji
Historia zmian
12

Płatności CashBill

Transkrypt

Podobne dokumenty

Oferta handlowa

Budowa centrum dystrybucyjno-szkoleniowo