wplatba SOAP api Technická dokumentáce 1
OBSAH ÚČEL DOKUMENTU... 3 TECHNICKÝ KONTAKT... 3 LEGENDA... 3 PLATEBNÍ METODY... 4 KOMUNIKACE... 4 TESTOVÁNÍ... 4 JAK POSTUPOVAT V PŘÍPADĚ PROBLÉMŮ... 4 CARDPAY... 5 VYTVOŘENÍ TRANSAKCE... 5 ZPRACOVÁNÍ ODPOVĚDI... 5 COMFORTPAY... 6 VYTVOŘENÍ TRANSAKCE... 6 ZPRACOVÁNÍ ODPOVĚDI... 7 M-PLATBY... 8 VYTVOŘENÍ TRANSAKCE... 8 ZPRACOVÁNÍ ODPOVĚDI... 8 BANKOVNÍ TLAČÍTKA... 9 VYTVOŘENÍ TRANSAKCE... 9 ZPRACOVÁNÍ ODPOVĚDI... 9 TRANSFER... 10 VYTVOŘENÍ TRANSAKCE... 10 ZPRACOVÁNÍ ODPOVĚDI... 10 2
ÚČEL DOKUMENTU Tento dokument popisuje SOAP platební rozhraní služby wplatba, které poskytuje tyto platební nástroje: - Cardpay - jednorázové platby platebními kartami v prostředí internetu - Comfortpay - opakované platby platebními kartami v prostředí internetu - M-platba - platby za služby či zboží prostřednictvím mobilního telefonu (wap, mobilní internet a internet) - Bankovní tlačítka - bankovní online převody v reálném čase z prostředí internetového bankovnictví plátce Tento dokument je určen pro programátora na straně Klienta. Wsdl platebního API je dostupné na https://platebnibrana.wplatba.cz:8443/wps/api?wsdl. Autorizační údaje jako login, heslo a id eshopu obdržíte po podepsání smlouvy. TECHNICKÝ KONTAKT Email: servis@wplatba.cz LEGENDA Uživatel - návštěvník webových stránek nebo aplikace Klient - webové stránky nebo aplikace Obchodník - banka, operátor Platební brána - rozhraní mezi klientem a obchodníkem Odpovědní URL - URL adresa, na kterou budou chodit odpovědi platební brány 3
PLATEBNÍ METODY KOMUNIKACE Klient požádá platební bránu o vytvoření transakce. Pokud požadavek neprojde validací např. z důvodu volání z nepovolené IP nebo chybějících parametrů, volání skončí výjimkou PaymentFault s popisem, co se stalo špatně. Pokud jsou údaje v pořádku, služba vrátí objekt typu Response, který má atributy successful, redirect a errormessage. V případě, že successful = true, je platba založena, a uživatel může být přesměrován na URL z atributu redirect. Jinak je nastaven atribut errormessage, ve kterém je popis chyby volání. Může jít např. o chybné přihlašovací údaje nebo volání nepovoleného platebního nástroje. Pro import webové služby do klientské aplikace lze použít např. wsimport pro jazyk java, nebo xsd.exe, případně import v MS Visual Studiu pro.net. TESTOVÁNÍ Postup je stejný jako v kapitolách Vytvoření transakce, pouze s tím rozdílem, že se při volání nastaví parametr debug. Možné testovací scénáře: PAID - Transakce zaplacena REFUSED - Transakce odmítnuta CANCELED - Transakce zrušena EXPIRED - Expirace transakce REFUNDED Transakce refundovaná JAK POSTUPOVAT V PŘÍPADĚ PROBLÉMŮ V případě, že se při pokusu o platbu vrátí odpověď obsahující informace o chybě, kontaktujte technickou podporu (servis@wplatba.cz) a přiložte výpis errormesasge nebo PaymentFault s časem neúspěšného volání. 4
CARDPAY Služba Cardpay umožňuje zákazníkům bezhotovostní platbu za zakoupené zboží a služby na internetovém eshopu pomocí platebních karet VISA, MASTER CARD a MAESTRO. VYTVOŘENÍ TRANSAKCE 1) Vytvoření instance třídy Cardpay 2) Nastavení společných parametrů: login, password součást smlouvy eshopid identifikátor eshopu, součást smlouvy answerurl URL, na které budou chodit odpovědi platebního systému cancelurl URL, na které bude uživatel přesměrován v případě zrušení platby okurl URL, na které bude uživatel přesměrován v případě, že platba proběhla v pořádku homeurl URL, na které bude region CZ/SK podle toho, jestli jde o český nebo slovenský eshop reference variabilní symbol platby price cena platby content stručný popis platby, který bude vidět ve výpisu plateb email nepovinný parametr, který určuje, zda bude uživatel informován o průběhu platby emailem debug nepovinný parametr, viz testování 3) Nastavení specifických parametrů pro cardpay: card typ karty, nepovinný parametr. Možnosti: VISA, VISAELECTRON, MASTERCARD, MAESTRO langure jazyk, ve kterém bude platební brána banky, možnosti: CZ, SK, HU, FR, ES, PL, IT, DE, EN currency: měna platby, možnosti: CZK, EUR, USD 4) Zavolání webové metody paycard, předání mu této instance jako parametr 5) Přesměrování uživatele na URL z odpovědi API, které bude v atributu redirect. ZPRACOVÁNÍ ODPOVĚDI Odpověď API přijde POSTem na answerurl v parametru response ve tvaru errorno:status:var_symbol:zaplaceno:zalozeno:reason:erronno2:altpaidprice:comfortpayid. Status: status platby, jedna z možností CREATED, VALIDATED, ERROR, OTHER reason: důvod statusu, jedna z možností UNVERIFIED, CANCELED, EXPIRED, REFUSED, PAID, UNAVALIABLE, REFUNDED,OTHER zaplaceno: Jaká část platby je zaplacena 5
COMFORTPAY Služba Comfortpay je rozšíření služby CARDPAY a umožňuje koncovému zákazníkovi uložit si svoji platební kartu pro další nákupy či opakované platby. Při dalším nákupu už nemusí zákazník zadávat údaje ze své platební karty, stačí vybrat pouze platbu Comfortpay, tedy již dříve uloženou platební kartu. Zákazník musí být jednoznačně srozuměn s tím, že údaje jeho platební karty budou bezpečně uloženy pro další nákupy a tuto skutečnost musí odsouhlasit. Obchodník tento souhlas musí evidovat a na vyžádání doložit. VYTVOŘENÍ TRANSAKCE 1) Vytvoření instance třídy Comfortpay 2) Nastavení společných parametrů: login, password součást smlouvy eshopid identifikátor eshopu, součást smlouvy answerurl URL, na které budou chodit odpovědi platebního systému cancelurl URL, na které bude uživatel přesměrován v případě zrušení platby okurl URL, na které bude uživatel přesměrován v případě, že platba proběhla v pořádku homeurl URL, na které bude region CZ/SK podle toho, jestli jde o český nebo slovenský eshop reference variabilní symbol platby price cena platby content stručný popis platby, který bude vidět ve výpisu plateb email nepovinný parametr, který určuje, zda bude uživatel informován o průběhu platby emailem debug nepovinný parametr, viz testování 3) Nastavení specifických parametrů pro cardpay: card typ karty, nepovinný parametr. Možnosti: VISA, VISAELECTRON, MASTERCARD, MAESTRO language jazyk, ve kterém bude platební brána banky, možnosti: CZ, SK, HU, FR, ES, PL, IT, DE, EN currency: měna platby, možnosti: CZK, EUR, USD 4) Nastavení specifických parametrů pro comfortpay: registercard uložit kartu pro další použití, hash uložené karty bude v odpovědi API v parametru comfortpayid usecard hash dříve uložené karty. Parametry usecard a registercard nelze použít najednou. 5) Zavolání webové metody paycomfortpay, předání mu této instance jako parametr 6) Přesměrování uživatele na URL z odpovědi API, které bude v atributu redirect. 6
ZPRACOVÁNÍ ODPOVĚDI Odpověď API přijde POSTem na answerurl v parametru response ve tvaru errorno:status:var_symbol:zaplaceno:zalozeno:reason:erronno2:altpaidprice:comfortpayid. Status: status platby, jedna z možností CREATED, VALIDATED, ERROR, OTHER reason: důvod statusu, jedna z možností UNVERIFIED, CANCELED, EXPIRED, REFUSED, PAID, UNAVALIABLE, REFUNDED, OTHER zaplaceno: Jaká část platby je zaplacena comfortpayid: hash použité karty, který lze použít v následujících platbách 7
M-PLATBY M-platba představuje univerzální a současně jednoduché platební řešení, které splňuje všechny požadavky na bezpečnost platby v prostředí klasického i mobilního internetu. Úhrada je realizována výhradně prostřednictvím zabezpečené platební brány mobilního operátora. VYTVOŘENÍ TRANSAKCE 1) Vytvoření instance třídy Comfortpay 2) Nastavení společných parametrů: login, password součást smlouvy eshopid identifikátor eshopu, součást smlouvy answerurl URL, na které budou chodit odpovědi platebního systému cancelurl URL, na které bude uživatel přesměrován v případě zrušení platby okurl URL, na které bude uživatel přesměrován v případě, že platba proběhla v pořádku homeurl URL, na které bude region CZ/SK podle toho, jestli jde o český nebo slovenský eshop reference variabilní symbol platby price cena platby content stručný popis platby, který bude vidět ve výpisu plateb email nepovinný parametr, který určuje, zda bude uživatel informován o průběhu platby emailem debug nepovinný parametr, viz testování 3) Nastavení specifických parametrů pro mpay: operator: jedna z možností TMOBILE_CZ, O2_CZ, VODAFONE_CZ msisdn: telefonní číslo uživatele ve tvaru 420XXXXXXXXX 4) Zavolání webové metody paympay, předání mu této instance jako parametr 5) Přesměrování uživatele na URL z odpovědi API, které bude v atributu redirect. ZPRACOVÁNÍ ODPOVĚDI Odpověď API přijde POSTem na answerurl v parametru response ve tvaru errorno:status:var_symbol:zaplaceno:zalozeno:reason:erronno2:altpaidprice:comfortpayid. Status: status platby, jedna z možností CREATED, VALIDATED, ERROR, OTHER reason: důvod statusu, jedna z možností UNVERIFIED, CANCELED, EXPIRED, REFUSED, PAID, UNAVALIABLE, REFUNDED, OTHER zaplaceno: Jaká část platby je zaplacena 8
BANKOVNÍ TLAČÍTKA Jedná se o rychlý, pohodlný a velmi oblíbený bankovní platební nástroj, kdy zákazník kliknutím na tlačítko je přesměrován na internetové bankovnictví jeho banky, kde na něj čeká k autorizaci již vygenerovaný platební příkaz. Zákazník se tak pohybuje v prostředí internetového bankovnictví, které dobře zná a úhrada je pro něj bezpečná a důvěryhodná VYTVOŘENÍ TRANSAKCE 1) Vytvoření instance třídy BankButton 2) Nastavení společných parametrů: login, password součást smlouvy eshopid identifikátor eshopu, součást smlouvy answerurl URL, na které budou chodit odpovědi platebního systému cancelurl URL, na které bude uživatel přesměrován v případě zrušení platby okurl URL, na které bude uživatel přesměrován v případě, že platba proběhla v pořádku homeurl URL, na které bude region CZ/SK podle toho, jestli jde o český nebo slovenský eshop reference variabilní symbol platby price cena platby content stručný popis platby, který bude vidět ve výpisu plateb email nepovinný parametr, který určuje, zda bude uživatel informován o průběhu platby emailem debug nepovinný parametr, viz testování 3) Nastavení specifických parametrů pro mpay: bank vybraná banka. Možnosti: CZ_PAYU, SK_UNICREDIT, SK_POSTBANK, SK_CSOB, SK_SBERBANK, SK_SPOROPAY, SK_OTP, SK_TATRABANKA, SK_VUB, CZ_RAIFFEISEN language jazyk, ve kterém bude platební brána banky, možnosti: CZ, SK, HU, FR, ES, PL, IT, DE, EN currency: měna platby, možnosti: CZK, EUR, USD 4) Zavolání webové metody paybutton, předání mu této instance jako parametr 5) Přesměrování uživatele na URL z odpovědi API, které bude v atributu redirect. ZPRACOVÁNÍ ODPOVĚDI Odpověď API přijde POSTem na answerurl v parametru response ve tvaru errorno:status:var_symbol:zaplaceno:zalozeno:reason:erronno2:altpaidprice:comfortpayid. Status: status platby, jedna z možností CREATED, VALIDATED, ERROR, OTHER reason: důvod statusu, jedna z možností UNVERIFIED, CANCELED, EXPIRED, REFUSED, PAID, UNAVALIABLE, REFUNDED, OTHER zaplaceno: Jaká část platby je zaplacena 9
TRANSFER Bankovní převod na účet - standardní bankovní převod na účet platební brány wplatba. VYTVOŘENÍ TRANSAKCE 1) Vytvoření instance třídy Transfer 2) Nastavení společných parametrů: login, password součást smlouvy eshopid identifikátor eshopu, součást smlouvy answerurl URL, na které budou chodit odpovědi platebního systému cancelurl URL, na které bude uživatel přesměrován v případě zrušení platby okurl URL, na které bude uživatel přesměrován v případě, že platba proběhla v pořádku homeurl URL, na které bude region CZ/SK podle toho, jestli jde o český nebo slovenský eshop reference variabilní symbol platby price cena platby content stručný popis platby, který bude vidět ve výpisu plateb email nepovinný parametr, který určuje, zda bude uživatel informován o průběhu platby emailem debug nepovinný parametr, viz testování 3) Nastavení specifických parametrů pro Transfer: currency: měna platby, možnosti: CZK, EUR, USD 4) Zavolání webové metody paytransfer, předání mu této instance jako parametr 5) Přesměrování uživatele na URL z odpovědi API, které bude v atributu redirect. ZPRACOVÁNÍ ODPOVĚDI Odpověď API přijde POSTem na answerurl v parametru response ve tvaru errorno:status:var_symbol:zaplaceno:zalozeno:reason:erronno2:altpaidprice:comfortpayid. Status: status platby, jedna z možností CREATED, VALIDATED, ERROR, OTHER reason: důvod statusu, jedna z možností UNVERIFIED, CANCELED, EXPIRED, REFUSED, PAID, UNAVALIABLE, REFUNDED, OTHER zaplaceno: Jaká část platby je zaplacena 10