Pomocí této knihovny lze pohodlně integrovat platební bránu ČSOB do vašeho e-shopu nebo jiné aplikace v PHP bez nutnosti přímo pracovat s jejím API, volat nějaké metody, ověřovat podpisy apod.
Podrobnosti o API platební brány, o generování klíčů a o jednotlivých krocích zpracováná platby najdete na https://github.com/csob/paymentgateway. Testovací platební karty jsou na wiki zde
Pozor pozor! Často na to někdo naráží, že to raději vypíchnu tady nahoře. Používá se zde VÁŠ soukromý klíč a veřejný klíč BANKY. Ne obráceně. Ne váš veřejný klíč.
Na podzim 2019 vydala banka API verze 1.8, které kromě několika přidaných funkcí zavádí také malé, nicméně zpětně nekompatibilní, změny.
Používáte-li tedy knihovnu ve své aplikaci a používáte adresu nejnovější verze GatewayUrl::PRODUCTION_LATEST, tak pozor, updatem knihovny na verzi 1.8
dojde i k update na API 1.8 a některé věci tedy mohou fungovat jinak.
- Knihovna nyní podporuje ČSOB eAPI 1.8 a podpisy pomocí SHA 256. U metod API, které mají v knihovně svoji vlastní metodu, např. paymentInit nebo customerInfo,
jsou všechny změny v API 1.8 již zohledněny. Voláte-li nějaké pokročilejší metody ručně přes
customRequest(), zkontrolujte, že nedošlo k změně v API. - V Configu lze explicitně nastavit, jakou adresu a jakou verzi API má knihovna používat. Nespecifikujte nic, má-li se vše nastavit automaticky.
- Nové platební metody (MallPay, ApplePay) nejsem dost dobře schopný otestovat, neexistují pro ně tedy přesné metody v knihovně. Používejte tedy univerzální metodu
customRequest(), parametry zadejte manuálně a knihovna alespoň odešle request a ověří odpověď. Pokud pro tyto platby někdo vyvine a otestuje jednotlivé metody do knihovny do Client třídy, nechť pošle PR, rád ho zapojím. - Pro platbu platebními tlačítko ČSOB a ERA je od verze 1.8 nová metoda - buttonInit(). Pro API < 1.8 používejte nadále paymentButton(). Ve verzích 1.8 a 1.8.1 měla buttonInit() chybu, která je ve verzi 1.8.2 opravena.
- Ve třídě Config přibyla možnost nastavit $sslVersion pro explicitní určení, jaká verze SSL/TLS se má pro komunikaci s bankou použít.
Jako výchozí adresa je testovací platební brána aktuální verze (nyní tedy 1.8 - GatewayUrl::TEST_1_8).
Doporučuji používat konstanty třídy GatewayUrl, které obsahují URL jednotlivých verzí API.
$config->url = GatewayUrl::TEST_1_7;
$config->url = GatewayUrl::PRODUCTION_1_8;
$config->url = GatewayUrl::PRODUCTION_LATEST;
Nejjednodušeji nainstalujete pomocí Composeru:
composer require ondrakoupil/csob-eapi-paygate
Pokud nepoužíváte Composer, stačí někam nakopírovat soubor dist/csob-client.php a includnout ho - obsahuje všechny potřebné třídy pohromadě.
Kromě této knihovny se bude hodit:
- Merchant ID - anonymní ID lze vygenerovat na stránce keygenu, anebo použijte to ID, které přidělí banka
- Klíče pro podepisování a verifikaci podpisů - opět získáte v keygenu. Při implementaci použijete jen svůj privátní klíč. Ten veřejný odešlete přes keygen bance a pak na něj můžete klidně zapomenout.
- Veřejný klíč banky - lze stáhnout z Githubu ČSOB. Pozor, liší se pro testovací a ostrou bránu.
Knihovna se skládá z tříd:
- Client - hlavní třída, se kterou budeme pracovat
- Config - nastavení parametrů komunikace s bránou, klíčů, Merchant ID atd. a různých výchozích hodnot
- Payment - představuje jednu platbu
- Crypto - zajišťuje podepisování a ověřování podpisů
- Extension - třída představující rozšíření. Lze používat buď přímo třídu Extension, anebo jednotlivé odděděné specializované třídy.
Všechny třídy jsou v namespace OndraKoupil\Csob, je tedy třeba je na začátku souboru uvést pomocí
use, anebo vždy používat celé jméno třídy včetně namespace. Zde uvedené příklady předpokládají,
že jste už použili use.
Nejdřív ze všeho je třeba vytvořit objekt Config a nastavit v něm potřebné hodnoty.
Ten pak předáte objektu Client a voláte jeho metody, které odpovídají jednotlivým
metodám, které API normálně nabízí.
$config = new Config(
"My Merchant ID",
"path/to/my/private/key/file.key",
"path/to/bank/public/key.pub",
"My shop name",
// Adresa, kam se mají zákazníci vracet poté, co zaplatí
"https://www.my-eshop.cz/return-path.php",
// URL adresa API - výchozí je adresa testovacího (integračního) prostředí,
// až budete připraveni přepnout se na ostré rozhraní, sem zadáte
// adresu ostrého API. Nezapomeňte také na ostrý veřejný klíč banky.
GatewayUrl::TEST_LATEST
);
$client = new Client($config);Pozor - používá se zde VÁŠ soukromý klíč a veřejný klíč BANKY. A také nezapomeňte, že testovací a ostré API má odlišný veřejný klíč.
Config umožňuje nastavit i nějaké další parametry a různé výchozí hodnoty, viz dokumentace.
Pro ověření, že spojení funguje a požadavky se správně podepisují, lze využít
metody testGetConnection() and testPostConnection(), které volají API metodu echo.
try {
$client->testGetConnection();
$client->testPostConnection();
} catch (Exception $e) {
echo "Something went wrong: " . $e->getMessage();
}Pro založení nové platby je třeba vytvořit objekt Payment, nastavit mu požadované hodnoty
a pak ho předat do paymentInit(). Pokud je vše v pořádku, API přidělí platbě PayID. To
je třeba někam uložit, bude se později hodit pro volání dalších metod.
Pomocí $payment->addCartItem() se přidávají položky do objednávky. V současné verzi
musí mít platba jednu nebo dvě položky, v budoucích verzích se toto omezení má změnit.
Pozor, všechny řetězce by měly být v UTF-8. Používáte-li jiné kódování, je třeba je všude, kde hrozí
nějaká diakritika (zejména u názvu položky v košíku), převádět pomocí funkce iconv.
$payment = new Payment("1234");
$payment->addCartItem("Zakoupená věcička", 1, 10000);
$response = $client->paymentInit($payment);
$payId = $payment->getPayId();
$payId = $response["payId"];Toto je nezbytné minimum - v objektu $payment toho lze nastavit mnohem více. A pozor, cena
se uvádí v setinách základní jednotky měny (v haléřích nebo v centech) - tj. 10000 znamená
jen 100 Kč.
Při zavolání paymentInit() se zadanému objektu $payment nastaví jeho PayID, odkud ho lze
přečíst přes getter, anebo ho lze získat z vráceného pole.
Po úspěšném založení platby je třeba přesměrovat prohlížeč zákazníka na platební bránu,
jejíž adresu vygeneruje getPaymentProcessUrl(). Jako pomůcka je tu rovnou i metoda
redirectToGateway(), která toto přesměrování rovnou provede.
$url = $client->getPaymentProcessUrl($payment);
redirectBrowserTo($url); // fiktivní funkce pro přesměrování
// NEBO
$client->redirectToGateway($payment);
terminateApp(); // fiktivní funkce pro ukončení skriptuJako argument lze používat buď $payment objekt z předchozího volání, anebo PayID jako obyčejný string.
Poté, co zákazník zadá potřebné údaje na platební bráně a vše se ověří a schválí,
brána ho vrátí na Return URL, kterou jste nastavili v Configu nebo v Payment objektu.
Na této URL byste měli buď ověřit stav platby přes paymentStatus() anebo
jednoduše zpracovat příchozí data pomocí metody receiveReturningCustomer(), která zkontroluje platnost
podpisu příchozích dat a vyextrahuje z nich užitečné hodnoty.
$response = $client->receiveReturningCustomer();
if ($response["paymentStatus"] == 7) {
// nebo také 4, záleží na nastavení closePayment
echo "Platba proběhla, děkujeme za nákup.";
} else {
echo "Něco se pokazilo, sakra...";
}Podrobnosti o stavech platby jsou zde na wiki platební brány.
Kdykoliv lze jednoduše zjistit, v jakém stavu je zrovna platba:
$status = $client->paymentStatus($payId);Pokud potřebujete více detailů než jen číslo stavu, dejte druhý argument $returnStatusOnly na false,
metoda pak vrátí array s různými podrobnostmi.
Metoda paymentReverse() zruší dosud nezprocesovanou platbu, paymentClose() potvrdí platbu
a paymentRefund() vrátí již proběhlou platbu zpět plátci.
Pozor, platba musí být ve správném stavu, jinak nastane chyba a vyhodí se výjimka. Pokud nastavíte
druhý argument $ignoreWrongPaymentStatusError na true, tak se tato konkrétní chyba tiše ignoruje a metoda jen vrátí null.
Všechny ostatní chyby nadále vyhazují výjimku.
$client->paymentReverse($payId);
$client->paymentClose($payId);
$client->paymentRefund($payId);Počínaje API 1.5 umožňuje platební brána vrátit jen část prostředků pomocí netody paymentRefund()
nebo potvrdit transakci s nižší než původně autorizovanou částkou u metody paymentClose().
Jako třetí argument těchto metod lze zadat požadovanou částku k vrácení v setinách základní měny (pozor!):
// Potvrdit transakci jen na 100 Kč
$client->paymentClose($payId, false, 10000);
// Vrátit 100 Kč
$client->paymentRefund($payId, false, 10000);paymentRefund() občas v testovacím prostředí vrací HTTP stav 500, což vede k vyhození výjimky.
Dle tohoto issue jde o bug v testovacím prostředí platební brány, který zatím není vyřešen.
Metoda customerInfo() ověřuje, zda zákazník se zadaným ID (např. e-mailem) už někdy
platil kartou a pokud ano, lze se nějak zachovat (např. vypsat personalizovanou hlášku):
$hasCards = $client->customerInfo($someCustomerId);
if ($hasCards) {
echo "Chcete zase zaplatit kartou?";
} else {
echo "Nabízíme tyto možnosti platby: ...";
}API 1.8 tuto metodu přejmenovalo na echo/customer, knihovna zvolí vhodný endpoint sama, v PHP ale volejte vždy customerInfo()
Jde o zatím neveřejnou funkce platební brány. Umožní zobrazit minimalistický iframe a celé odbavení platby a objednávky udělat v iframu vloženém do vašeho webu namísto přechodu na platební bránu.
Pro aktivaci je nutné kontaktovat ČSOB a požádat o aktivování této funkce. Při té příležitosti vám také pošlou podrobnější dokumentaci.
Poté, co je funkce povolená, můžete místo payment/process volat payment/checkout.
Pokud pro vaše merchantId není funkce povolená, brána zobrazí chybovou hlášku.
$url = $client->getPaymentCheckoutUrl($payment, $oneClickPaymentCheckbox);
redirect($url);$payment může být Payment objekt anebo prosté PayID, obdobně jako u jiných metod.
Pro $oneClickPaymentCheckbox použijte jednu z možností popsanou v PHPDocu zdrojového kódu metody.
Další parametry jsou popsané v dokumentaci metody.
Díky @rootpd.
Metody paymentButton() pro API < 1.8 a buttonInit() pro API >= 1.8 slouží k platbě tzv. platebním tlačítkem. Podrobnější parametry jsou v dokumentaci obou metod.
Tyto metody vrací pole s různými daty, mimo jiné redirect, ve kterém je uvedena adresa,
na níž máte uživatele přesměrovat. Nepoužívejte tedy redirectToGateway() nebo něco podobného,
ale přímo přesměrujte uživatele na adresu, kterou banka vrátí.
Počínaje API 1.5 lze provádět opakované platby. Jak přesně to funguje se dočtete na Wiki ČSOB. Zhruba to je takto:
- necháte zákazníka autorizovat platební šablonu tak, že provedete normálně
celý platební proces jako obvykle, ale objektu Payment před voláním
paymentInit()nastavíte$payOperationnaPayment::OPERATION_ONE_CLICK, nejlépe zavoláním$payment->setOneClickPayment(true) - zákazník pak zadá číslo karty, kód a provede 3D ověření jako u běžné platby
- vy si uložíte PayID, abyste se na tuto autorizovanou transakci mohli odkazovat
- od API verze 1.8 existuje
paymentOneClickEcho()pro ověření, zda je originální PayID stále použitelné. - pak můžete kdykoliv zavolat metodu
paymentOneClickInit()s PayID původní transakce a s novým Payment objektem. Tím se založí nová platba. Následným zavolánímpaymentOneClickStart()se platba provede. - nová platba dostane své vlastní PayID a lze s ní pracovat jako s jakoukoliv jinou platbou
- API 1.8 změnilo název endpointu, knihovna to sama zohlední, v PHP vždy volejte paymentOneClickInit()
nebo paymentOneClickStart(). Také se v paymentOneClickInit přidal povinný parametr
clientIp.
Client má vestavěné jednoduché logování. Jeden log slouží pro business-level zprávy
("platba XYZ proběhla úspěšně"), do druhého logu (traceLog) se zaznamenává podrobná
komunikace s API a různé detailní technikálie.
Lze buď jednoduše zadat cestu do souboru, kam se budou zprávy zaznamenávat, anebo dát callback, který zprávy přesměruje do libovolného loggeru, který vaše aplikace používá. Logy lze nastavit buď v konstruktoru Client objektu, anebo pomocí setterů.
$client->setLog("some/file/log.txt");
$client->setTraceLog(function($message) use ($myLogger) {
$myLogger->log($message);
});Pokud potřebujete poslat požadavek na API metodu, která není v této knihovně speciálně implementovaná (zatím např. metody Masterpass, ApplePay nebo MallPay), lze využít customRequest() metodu. Je potřeba jen pohlídat, v jakém pořadí jsou zadána vstupní data a v jakém pořadí jsou data v odpovědi skládána do řetězce pro ověření podpisu odpovědi.
$client->customRequest(
// URL, jenom konec za společnou adresou API, např. "payment/init"
$methodUrl,
// Array se vstupními daty. Pořadí položek v array je důležité.
// Na vhodná místa lze vložit prázdné dttm a merchantId, doplní se automaticky.
$inputPayload,
// Array s názvy políček v odpovědi v požadovaném pořadí dle dokumentace.
// U vnořených objektů a polí lze pracovat s tečkou.
// Například: array('payId', 'dttm', 'resultCode', 'resultMessage', 'redirect.method', 'redirect.url')
$expectedOutputFields = array(),
// Volitelně nějaké extensions
$extensions = array(),
$method = "POST",
// Zalogovat vždy podrobně celou návratovou hodnotu z API?
$logOutput = false,
// Pokud z nějakého důvodu selhává ověření podpisu, lze ho takto úplně deaktivovat.
// Nicméně pak je nutné ručně takovou situaci ošetřit.
$ignoreInvalidReturnSignature = false
)V $expectedOutputFields může určitá hodnota začínat na ?, v takovém případě s epovažuje za nepovinnou a není-li v odpovědi banky
vůebc zahrnuta, nebude do základu podpisu zahrnutá. Pokud nezačíná na ?, do základu podpisu se dá prázdný řetězec.
Rozšíření jsou implementována pomocí třídy Extension a volitelně odděděných tříd (momentálně jen pro EET). Objekty této třídy pak lze přikládat do každé volané metody. Do požadavků se pak budou přidávat dodatečná data, a u odpovědí se budou automaticky validovat podpisy odpovědí.
Každé rozšíření má své extension ID (definované v dokumentaci od banky).
Pokud má rozšíření přidat nějaká další data do požadavku, je třeba zavolat setInputData() a předat
dodatečná data do požadavku jako array. Pořadí prvků v array je důležité, podle něj se sestaví
signature řetězec a podpis. Vždy se podívejte do dokumentace, v jakém pořadí mají parametry být, a
to dodržujte. Políčka dttm a extension můžete klidně nechat prázdné (false nebo null), hodnota se doplní automaticky,
ale je nutné je do array na patřičné místo dát.
Alternativně můžete třídu oddědit a implementovat si po svém metodu getRequestSignatureBase(),
která by měla vracet řetězec sloužící jako základ pro podpis.
Pokud rozšíření přidává rozšíření nějaká data do odpovědi z API, tak se k těmto datům dostanete pomocí
metody getResponseData().
Je možné nastavit ověření podpisu odpovědi pomocí setExpectedResponseKeysOrder(). Této metodě předáte array s názvy políček
z odpovědi v tom pořadí, v jakém mají být v podepsaném řetězci. Alternativně můžete oddědit Extension do vlastní třídy
a implementovat metodu verifySignature() po svém.
Pokud se nedaří ověřit podpis odpovědi, můžete pomocí setStrictSignatureVerification(false) vypnout ověřování podpisu
pro dané rozšíření. Po zavolání API metody je pak možné se přes isSignatureCorrect() doptat, zda byl podpis v pořádku,
a pokud nebyl, nějak to řešit po svém.
Pro jedno volání metody je možné předat více rozšíření, stačí do patřičného parametru metody Client objektu předat array objektů Extension, ne jen jediný objekt.
Pokud máte aktivované rozšíření trxDates, je v metodě paymentStatus() možné předat objekt třídy DatesExtension. Po zavolání metody se pak z DatesExtension dají přečíst požadovaná data jako DateTime objekty.
$extension = new DatesExtension();
$status = $client->paymentStatus($payment, true, $extension);
echo $extension->getCreatedDate()->format("j. n. Y");Dostupné jsou metody getCreatedDate(), getSettlementDate() a getAuthDate(), které vracejí DateTime anebo null,
pokud dané datum v odpovědi nebylo vůbec uvedené. Také pozor, settlementDate je s přesností pouze na dny, ne na sekundy.
Pokud máte aktivované rozšíření maskClnRP, je v metodě paymentStatus() možné předat objekt třídy CardNumberExtension. Po zavolání metody se pak z CardNumberExtension dá přečíst maskované číslo karty a její expirace. Nezapomeňte ale na to, že toto rozšíření je dostupné pouze pro "one click" platby.
$extension = new CardNumberExtension();
$status = $client->paymentStatus($payment, true, $extension);
echo $extension->getMaskedCln() . ' ' . $extension->getExpiration();Dostupné metody jsou getMaskedCln(), getLongMaskedCln() a getExpiration()
Protože extension pro EET je o dost složitější, jsou připraveny již specializované třídy pro jednotlivé API metody:
- EETInitExtension pro payment/init a payment/oneclick/init
- EETCloseExtension pro payment/close
- EETRefundExtension pro payment/refund
- EETStatusExtension pro payment/status
Při inicializaci platby přes payment/init je třeba při vytváření extension objektu předat
objekt třídy EETData. Jeho public proměnné naplňte potřebnými hodnotami (tři jsou povinné
a je třeba je vyplnit už v konstruktoru). Význam jednotlivých proměnných je podrobněji popsán na
Wiki ČSOB v tomto článku. Také si můžete pomocí $verificationMode zvolit,
zda se do EET má poslat jen v ověřovacím (testovacím) režimu.
Pozor, ceny v EETData jsou v korunách, narozdíl od cen v Payment třídě, kde jsou v haléřích.
Potvrzení nebo refundování platby (close a refund) je již možné udělat bez parametru, v tom případě se použijí data předaná v init metodě.
Pro zjištění stavu platby je extension EETStatusExtension, které se posílá spolu s payment/status.
Po zavolání paymentStatus() můžete z extension objektu přečíst výsledky pomocí getReport()
a případně getCancels(). Ty vrací objekt nebo objekty třídy EETReport s podrobnostmi.
Jsou k dispozici i zkratky getFIK(), getEETStatus(), getBPK() a getPKP(), přes které
získáte z odpovědi ty nejčastěji používaná data.
Nezapomeňte, že pro používání EET rozšíření je nutné mít tuto službu povolenou v bance.
Příklad (pomíjím namespaces):
// $client mám vytvořený podle postupu v předchozích bodech
// Vytvoříme si payment, klasicky
$payment = new Payment(12345);
$payment->addCartItem('Jedna položka', 1, 50000);
$payment->addCartItem('Druhá s nižší DPH', 1, 50000);
// Vytvoříme data pro EET. Jen parametry v konstruktoru jsou povinné.
$eetData = new EETData(123, 'abc123', 1000);
$eetData->priceStandardVat = 413.22;
$eetData->vatStandard = 86.78;
$eetData->priceFirstReducedVat = 454.55;
$eetData->vatFirstReduced = 45.45;
// Vytvoříme extension pro payment/init v ověřovacím režimu
$extensionInit = new EETInitExtension($eetData, true);
// Zavoláme payment/init a odešleme prohlížeč na bránu
$client->paymentInit($payment, $extensionInit);
$url = $client->getPaymentProcessUrl($payment);
// Nyní bychom měli přesměrovat prohlížeč na $url, nechat
// zákazníka zadat platbu, přijmout vrácená data atd.
// To nyní jakoby přeskakuji.
$extensionStatus = new EETStatusExtension();
$status = $client->paymentStatus($payment, true, $extensionStatus);
echo "<p>Stav platby je: $status</p>";
echo "<p>Stav odeslání do EET: " . $extensionStatus->getEETStatus() . "</p>";
echo "<p>FIK: " . $extensionStatus->getFIK() . "</p>";
// Mnoho dalších dat najdete v $extensionStatus->getReport()Pokud jste narazili na bug, něco nefunguje nebo máte návrh na zlepšení, přidejte issue nebo mě bez obav kontaktujte napřímo :-)