PHP knihovna pro práci s ČSOB platební bránou

Pomocí této knihovny lze pohodlně integrovat [platební bránu ČSOB][6] 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.

[English readme is here][english].

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/platebnibrana][1]. Testovací platební karty jsou na [wiki zde][7]

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][3]. Ne obráceně. Ne váš veřejný klíč.

Novinky

ČSOB API 1.9

V létě 2022 vydala banka API verze 1.9, které kromě několika přidaných funkcí zavádí také některé 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.9 dojde i k update na API 1.9 a některé věci tedy mohou fungovat jinak.

Novinky:

Změnily se metody pro práci s One click platbami. Nově se musí volat paymentOneClickInit() a potom paymentOneClickProcess()
Do objektu Payment pro metody paymentInit() a paymentOneClickInit() je nově možné předat mnohem, mnohem více dat o zákazníkovi a celé transakci. Tato data banka předá vydavateli karty, který podle svého interního algoritmu rozhodne, zda je nutné použít 3D ověření nebo ne. Předáním těchto pomocných dat údajně zvýšíte zákazníkův komfort, protože je pak větší šance, že vydavatel transakci schválí jako bezpečnou, neboť dostatečně odpovídá jeho dosavadnímu profilu chování a placení na internetu. Všechna tato nová data nastavíte pomocí $payment->setCustomer($customer) a $payment->setOrder($order) a pomocí tříd z namespacu Metadata.

Jako výchozí adresa je testovací platební brána aktuální verze (nyní tedy 1.9 - GatewayUrl::TEST_1_9).

Doporučuji používat konstanty třídy GatewayUrl, které obsahují URL jednotlivých verzí API.

$config->url = GatewayUrl::TEST_1_8;
$config->url = GatewayUrl::PRODUCTION_1_9;
$config->url = GatewayUrl::PRODUCTION_LATEST;

Instalace

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ě. Soubor si stáhněte přímo z Githubu, v exportovaném balíčku není.

Použití

Kromě této knihovny se bude hodit:

Merchant ID - anonymní ID lze vygenerovat na stránce [keygenu][2], 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][2]. 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][3]. 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.

Nastavení

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][10].

Test připojení

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();
}

Založení nové platby (payment/init)

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.

Volitelně lze od API 1.9 objektu Payment předat metadata o uživateli, což zjednoduší schválení transakce u vydavatele karty.

$customer = new Customer();
$customer->name = 'John Rambo';
$customer->email = 'john@rambo.cz';
$payment->setCustomer($customer);

Zaplacení (payment/process)

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í skriptu

Jako argument lze používat buď $payment objekt z předchozího volání, anebo PayID jako obyčejný string.

Návrat zákazníka

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][4].

Ověření stavu platby (payment/status)

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.

Potvrzení, zrušení, vrácení prostředků

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][4], 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][issue43] jde o bug v testovacím prostředí platební brány, který zatím není vyřešen.

Csob

Install / Use

README