Platební brána Benefity 1. Stanovení údajů Obchodníkovi se předají následující údaje: Parametr URL adresa pro placení SSL Uživatelské jméno pro placení Heslo pro placení Poznámka https://online.benefity.cz/payment/ 300625000 (pozn. pouze příklad) 300625000 (pozn. pouze příklad) 300-625-000 (pozn. pouze příklad) 2. Placení- předávání objednávek Objednávky jsou přijímány na URL adrese pro placeníssl definované Benefity (bod 1) a to metodou POST i GET. Přijímají se pouze požadavky kryptované SSL a autentizované Basic autentizací uživatelského jména:hesla obchodníka. Autentizačnířetězec má tvar 'Basic xxx', kde xxx je Base64 kódovánířetězce uživatelské jméno:heslo. Parametry placení jsou následující: Parametr Typ Poznámka URL ORDER_NUMBER ACCOUNT PIN AMOUNT BENEFIT_GROUP Řetězec ne řetězec numerický Url adresa obchodníka. Po skončení zpracování platby je požadavek přesměrován na adresu: URL?ORDER_NUMBER=ORDERNUMBER& ERR=xx, kde ERR je návratový kód. Pokud URL není uvedeno, je vrácen řetězec ERR=x, kde ERR je návratový kód. Přidělené číslo obchodníka od Bennefity (bod 1) Číslo objednávky. Musí být pro každkou platbu jednoznačné. Maximálně 15 znaků Číslo účtu. (pro testovani ucet 0000000000) PIN účtu. 4-10 znaku (pro testovani PIN 0000000000) Částka v Kč. Haléře jsou oddělené desetinou tečkou. Číslo skupiny benefitů (bod 3). Pro testovani napr. 42 3. Skupiny benefitů např. Skupina benefitů Hodnota Sport 42
Skupina benefitů Hodnota 4. Zpracování platby Všechna potřebná data zasílá obchodník. Platební správce se zákazníkem vůbec nekomunikuje. Po zaslání požadavku se vrátí výsledek v odpovědi. Odpověď obsahuje pole ERR návratové kódy. Jestliže je ERR rovno '0' (ERR=0) proběhla platba úspěsně. Jakýkoliv jiný návratový kód znamená neúspěšnou platbu (bod 5). 5. Návratové kódy Návratový kód význam 0 Platba byla přijata 1 Chybné číslo obchodník(a ). 2 Objchodník nemůže prodávat tuto skupinu (BENEFIT_GROUP) benefitů 3 Číslo objednavky (ORDER_NUMBER) již bylo použito. 4 Chybný účet (ACCOUNT) nebo pin (PIN). 5 Obchodník nesmí platit přes platební bránu. 6 Není vyplněn obchodník (MERCHANT_NIUMBER). 7 Není vyplněna skupina benefitu (BENEFIT_GROUP). 8 Není vyplněno číslo účtu (ACCOUNT). 9 Není vyplněn pin (PIN). 10 Není vyplněna cena (AMOUNT). 11 Cena (AMOUNT) je menší než nula. 12 Není vyplněno číslo objednávky (ORDER_NUMBER). 13 Účet (ACCOUNT) nemůže platit přes platební bránu. 14 Na účtě není dostatek prostředků. 5. Příklad pro platbu SSL Jestliže je obchodník plně nakonfigurován pošleme na URL adresa pro placení SSL na port 443: POST /payment/index.php http/1.1 Connection: Keep-Alive Authorization: Basic dxdjhvbjgidt28fds== Host: online.benefity.cz Accept-Encoding: deflate Content-Charset: 8859_2 Content-Length: xxx Content-Type: application/x-www-form-urlencoded =2569&ORDER_NUMBER=225&ACCOUNT=6140729618&PIN=1234&AMOUNT=1 256&BENEFIT_GROUP=1
Pokud se v poli ERR vrátí hodnota '0', pak platba proběhla úspěšně. 6. Dotaz na zůstatek na účtu Stejný princip komunikace jako při placení tedy: Objednávky jsou přijímány na URL adrese pro placeníssl definované Benefity (bod 1) a to metodou POST i GET. Přijímají se pouze požadavky kryptované SSL a autentizované Basic autentizací uživatelského jména:hesla obchodníka. Autentizačnířetězec má tvar 'Basic xxx', kde xxx je Base64 kódovánířetězce uživatelské jméno:heslo. Parametry dotazu zůstatku na účtu jsou následující: Parametr Typ Poznámka URL ACCOUNT PIN BENEFIT_GROUP Řetězec ne Url adresa obchodníka. Po skončení zpracování platby je požadavek přesměrován na adresu: URL?ACCOUNT=hodnota_ACCOUNT&BENE FIT_GROUP=hodnota_benefit_group&ZUSTAT EK=xx,ERR=err kde xx je hodnota zustatku a err je návratový kod. (err = 0 pokud je vše v pořádku) Pokud URL není uvedeno, je vrácen řetězec buď řetězec ZUSTATEK=xx,kde xx je z;statek v Kč nebo řetězec ERR=yy,pokud nastala nějaká chyba, kde yy je chybový kód stejný jako u standardního placení. Přidělené číslo obchodníka od Bennefity (bod 1) Číslo účtu. (pro testovani ucet 6873702395) PIN účtu. 10 znaku (pro testovani PIN 3087656520) Číslo skupiny benefitů (bod 3). Pro testovani napr. 42 DOTAZ_ZUSTATEK znak 1 Vložit hodnotu 1 Příklad dotazu na zůstatek: POST /payment/index.php http/1.1 Connection: Keep-Alive Authorization: Basic dxdjhvbjgidt28fds== Host: online.benefity.vh Accept-Encoding: deflate Content-Charset: 8859_2 Content-Length: xxx Content-Type: application/x-www-form-urlencoded =2569&ACCOUNT=6140729618&PIN=1234&BENEFIT_GROUP=1&DOTAZ_ZUS TATEK=1
Ukázková implementace v jazyce PHP: <?php /*.. require_module 'standard'; require_module 'curl'; class BenefityPaymentException extends Exception { const WRONG_ = 1; // Chybné číslo obchodník(a ). const WRONG_BENEFIT_GROUP = 2; // Obchodník nemůže prodávat tuto skupinu (BENEFIT_GROUP) benefitů const USED_ORDER_NUMBER = 3; // Číslo objednávky (ORDER_NUMBER) již bylo použito. const WRONG_CREDENTIALS = 4; // Chybný účet (ACCOUNT) nebo pin (PIN). const PAYMENT_NOT_ALLOWED = 5; // Obchodník nesmí platit přes platební bránu. const MISSING_ = 6; // Není vyplněn obchodník (). const MISSING_BENEFIT_GROUP = 7; // Není vyplněna skupina benefitu (BENEFIT_GROUP). const MISSING_ACCOUNT = 8; // Není vyplněno číslo účtu (ACCOUNT). const MISSING_PIN = 9; // Není vyplněn pin (PIN). const MISSING_AMOUNT = 10; // Není vyplněna cena (AMOUNT). const NEGATIVE_AMOUNT = 11; // Cena (AMOUNT) je menší než nula. const MISSING_ORDER_NUMBER = 12; // Není vyplněno číslo objednávky (ORDER_NUMBER). const ACCOUNT_NOT_ALOWED = 13; // Účet (ACCOUNT) nemůže platit přes platební bránu. const LOW_ACCOUNT_BALANCE = 14; // Na účtě není dostatek prostředků. const CONNECTION_ERROR = -1; // Chyba spojení const GENERAL_ERROR = -2; // Jiná chyba, např. špatné username/userpassword, chybný certifikát * @param int $code * @param string $name * @param Exception $previous public function construct($code, $name, Exception $previous=null) { parent:: construct($name, $code, $previous); class BenefityPayment { private $merchantnumber; private $username; private $userpassword; private $requesturl = 'https://online.benefity.cz/payment/'; * @var int private $requestport = 443; * @var boolean private $requestcertificatecheck = TRUE; * @param string $request * @return mixed private function doprocessrequest($request){ $curl = curl_init(); curl_setopt($curl, CURLOPT_URL, $this->requesturl.$request); curl_setopt($curl, CURLOPT_PORT, $this->requestport); curl_setopt($curl, CURLOPT_HEADER, 0); curl_setopt($curl, CURLOPT_SSL_VERIFYPEER, $this->requestcertificatecheck? 1 : 0); curl_setopt($curl, CURLOPT_RETURNTRANSFER, 1); curl_setopt($curl, CURLOPT_FORBID_REUSE, 1); curl_setopt($curl, CURLOPT_FRESH_CONNECT, 1); curl_setopt($curl, CURLOPT_POST, 0); curl_setopt($curl, CURLOPT_HTTPAUTH, CURLAUTH_BASIC); curl_setopt($curl, CURLOPT_USERPWD, $this->username.':'.$this->userpassword); $response = curl_exec($curl); if($response === FALSE){ throw new BenefityPaymentException(BenefityPaymentException::CONNECTION_ERROR, 'Error connecting to server: `'.curl_error($curl).'`'); else{ curl_close($curl); return trim($response); * @param string $username * @param string $userpassword
* @param string $merchantnumber public function construct($username, $userpassword, $merchantnumber){ $this->username = $username; $this->userpassword = $userpassword; $this->merchantnumber = $merchantnumber; * Enables testing mode public function settestingmode() { $this->requesturl = 'https://online.benefity.cz/payment/'; $this->requestport = 443; $this->requestcertificatecheck = FALSE; * Processes payment * @param string $benefitgroup * @param string $ordernumber * @param string $clientcard * @param string $clientpin * @param string $value public function dopayment($benefitgroup, $ordernumber, $clientcard, $clientpin, $value){ $request = '?='.urlencode($this->merchantnumber); $request.= '&ORDER_NUMBER='.urlencode($orderNumber); $request.= '&ACCOUNT='.urlencode($clientCard); $request.= '&PIN='.urlencode($clientPin); $request.= '&BENEFIT_GROUP='.urlencode($benefitGroup); $request.= '&AMOUNT='.urlencode($value); $response = $this->doprocessrequest($request); $result = /*.(array[string]string). array(); parse_str($response, $result); if(isset($result['err']) && $result['err'] === '0'){ return; elseif(isset($result['err']) && intval($result['err']) >= 1 && intval($result['err']) <= 14){ throw new BenefityPaymentException(intval($result['ERR']), 'Request denied'); elseif(isset($result['err'])){ returned error code: `'.$result['err'].'`'); else{ error'); * Get clients credit balance * @param string $benefitgroup * @param string $clientcard * @param string $clientpin * @return string public function getaccountbalance($benefitgroup, $clientcard, $clientpin){ $request = '?DOTAZ_ZUSTATEK=1'; $request.= '&='.urlencode($this->merchantnumber); $request.= '&ACCOUNT='.urlencode($clientCard); $request.= '&PIN='.urlencode($clientPin); $request.= '&BENEFIT_GROUP='.urlencode($benefitGroup); $response = $this->doprocessrequest($request); $result = /*.(array[string]string). array(); parse_str($response, $result); if(isset($result['zustatek'])){ return $result['zustatek']; elseif(isset($result['err']) && intval($result['err']) >= 1 && intval($result['err']) <= 14){ throw new BenefityPaymentException(intval($result['ERR']), 'Request denied'); elseif(isset($result['err'])){ returned error code: `'.$result['err'].'`'); else{ error'); $test = new BenefityPayment('123456789', '777', '123123123'); $test->settestingmode(); echo 'Balance:'.$test->getAccountBalance('34', '7151928516', '1234567890'); echo 'Payment:'; $test->dopayment('34', '123', '7151928516', '1234567890', '1');