Platební brána Benefity 1. Stanovení údajů Obchodníkovi se předají následující údaje:
Parametr
Poznámka
URL adresa pro placení SSL
https://online.benefity.cz/payment/
Uživatelské jméno pro placení
300625000 (pozn. pouze příklad)
Heslo pro placení
300625000 (pozn. pouze příklad)
MERCHANT_NUMBER
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 Řetězec nepovinný
URL
Poznámka 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.
MERCHANT_NUMBER
Textový povinný
Přidělené číslo obchodníka od Bennefity (bod 1)
ORDER_NUMBER
Numerický povinný
Číslo objednávky. Musí být pro každkou platbu jednoznačné. Maximálně 15 znaků
ACCOUNT
Numerický povinný
Číslo účtu. (pro testovani ucet 0000000000)
PIN
Textový řetězec
PIN účtu.
AMOUNT
numerický povinný
Částka v Kč. Haléře jsou oddělené desetinou tečkou.
BENEFIT_GROUP
Numerický povinný
Číslo skupiny benefitů (bod 3). Pro testovani napr. 42
4-10 znaku (pro testovani PIN 0000000000)
3. Skupiny benefitů např.
Skupina benefitů Sport
Hodnota 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 MERCHANT_NUMBER).
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 MERCHANT_NUMBER=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 URL
Typ Řetězec nepovinný
Poznámka 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í.
MERCHANT_NUMBER
Textový povinný
Přidělené číslo obchodníka od Bennefity (bod 1)
ACCOUNT
Numerický povinný
Číslo účtu. (pro testovani ucet 6873702395)
PIN
Numerický povinný
PIN účtu.
BENEFIT_GROUP
Numerický povinný
Číslo skupiny benefitů (bod 3). Pro testovani napr. 42
DOTAZ_ZUSTATEK
znak ‘1’
Vložit hodnotu ‘1’
10 znaku (pro testovani PIN 3087656520)
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 MERCHANT_NUMBER=2569&ACCOUNT=6140729618&PIN=1234&BENEFIT_GROUP=1&DOTAZ_ZUS TATEK=1
Ukázková implementace v jazyce PHP:
{ = 1; // Chybné číslo obchodník(a MERCHANT_NUMBER). = 2; // Obchodník nemůže prodávat tuto skupinu (BENEFIT_GROUP) = = = = = = = = = = = = = =
3; // Číslo objednávky (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_NUMBER). 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ů. -1; // Chyba spojení -2; // Jiná chyba, např. špatné userName/userPassword, chybný
/** * @param int $code * @param string $name * @param Exception $previous * @return void */ public function __construct($code, $name, Exception $previous=NULL) { parent::__construct($name, $code, $previous); } } class BenefityPayment { /** * @var string */ private $merchantNumber; /** * @var string */ private $userName; /** * @var string */ private $userPassword; /** * @var string */ private $requestUrl = 'https://online.benefity.cz/payment/'; /** * @var int */ private $requestPort = 443; /** * @var boolean */ private $requestCertificateCheck = TRUE; /** * @param string $request * @return mixed * @throws BenefityPaymentException */ 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 * @return void */ public function __construct($userName, $userPassword, $merchantNumber){ $this->userName = $userName; $this->userPassword = $userPassword; $this->merchantNumber = $merchantNumber; } /** * Enables testing mode * @return void */ 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 * @return void * @throws BenefityPaymentException */ public function doPayment($benefitGroup, $orderNumber, $clientCard, $clientPin, $value){ $request = '?MERCHANT_NUMBER='.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'])){ throw new BenefityPaymentException(BenefityPaymentException::GENERAL_ERROR, 'Unknown returned error code: `'.$result['ERR'].'`'); }else{ throw new BenefityPaymentException(BenefityPaymentException::GENERAL_ERROR, 'Unknown error'); } } /** * Get clients credit balance * @param string $benefitGroup * @param string $clientCard * @param string $clientPin * @return string * @throws BenefityPaymentException */ public function getAccountBalance($benefitGroup, $clientCard, $clientPin){ $request = '?DOTAZ_ZUSTATEK=1'; $request .= '&MERCHANT_NUMBER='.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'])){ throw new BenefityPaymentException(BenefityPaymentException::GENERAL_ERROR, 'Unknown returned error code: `'.$result['ERR'].'`'); }else{ throw new BenefityPaymentException(BenefityPaymentException::GENERAL_ERROR, 'Unknown 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');
