EasyPay — оплата товаров и услуг в Интернет

Уведомления


В системе EasyPay предусмотрена возможность оперативного информирования Поставщика товаров и услуг о совершаемых пользователями платежах.

Типы Уведомлений:
  • Уведомление на электронную почту ответственного лица Поставщика, указанного в Договоре. Текстовое сообщение на e-mail c основными параметрами платежа.
  • SMS-уведомление. SMS-сообщение на номер телефона, указанный в Договоре с Поставщиком. Доступно абонентам velcom, МТС, life:).
  • On-line Уведомление на URL Поставщика.
  • Извещение через mail2sms. Предоставляется мобильными операторами velcom, МТС и позволяет получать уведомления об оплатах в виде SMS-сообщения с электронной почты. Настроить режим уведомлений можно в Административном интерфейсе Поставщика в разделе "Настройки/Уведомления об оплатах".

On-line Уведомления на URL Поставщика

Уведомление Поставщика об оплатах осуществляется по протоколу HTTP (HTTPS) в виде специальных сообщений, отсылаемых POST-запросом. Подлежат уведомлению счета, которые были приняты в обработку, оплачены и не были отменены. Каждый такой счет-заказ подтверждается одним сообщением.

При необходимости формируется ежесуточный реестр платежей и отправляется по HTTP (HTTPS) в виде XML-документа.

Каждое сообщение подписывается электронной подписью, которая имеет вид строки md5-хэша, являющейся объединением всех полей счета-заказа и секретного ключа. Чтобы получить ключ, обратитесь в службу технической поддержки EasyPay.

Запрос с Уведомлением Поставщика о совершенном платеже будет отсылаться до тех пор, пока Поставщик его не примет, то есть до получения ответа с кодом "HTTP/1.0 200 OK".

В случае, если сайт Поставщика (по техническим или другим причинам) не может обработать запрос, он должен сгенерировать ответ с любым кодом ошибки, например "HTTP/1.0 400 Bad Request". Недопустимо отвечать кодом "HTTP/1.0 200 OK" на необработанное уведомление.

Уведомления отсылаются по специальному расписанию, но не более n раз, где n = 10 (задается EasyPay). Если сервер Поставщика после n-го запроса не дает положительного ответа, то на электронный адрес Поставщика отсылается письмо с предупреждением о сбое.

Расписание отправки уведомлений:

  • время первого уведомления: в течение 30 секунд после оплаты,
  • время следующего уведомления: время текущего уведомления + количество неудачных попыток отправки * интервал ожидания (120 секунд).
  • Схема работы

    1. Процессинговый центр формирует и отправляет сообщение об оплате, подписанное секретным ключом web_key, Поставщику. Ключ известен обеим сторонам, но в запросе не передается.

    2. Поставщик проверяет электронную подпись и сверяет данные заказа.

    3. Поставщик проверяет (одним или несколькими способами) оплату заказа:

  • отправка запроса через SOAP;
  • наличие информации об оплате заказа в Административном интерфейсе Поставщика.
  • Последний шаг не является обязательным, но его рекомендуется использовать как способ удостовериться в подлинности уведомления. Дополнительно Поставщик может установить проверку по доменному имени core.easypay.by или по IP-адресу.

    Реализация

    Для реализации уведомлений при подключении Поставщика к EasyPay задаются следующие параметры:

    notify_status – флаг включения механизма уведомления для конкретного Поставщика.
    0 – уведомление отключено,
    1 – уведомление включено.
    notify_url – URL Поставщика, на который отправляются сообщения.
    web_key – ключ (случайная последовательность символов), участвующий в электронной подписи сообщения.

    Формат сообщений и XML-документа реестра

    При формировании каждого сообщения, которое отсылается POST-запросом на соответствующий URL, используются следующие поля:

    Название полейФормат полейОписание полей
    order_mer_codeот 1 до 20 алфавитно-цифровых символовуникальный номер электронного счета. Формируется Поставщиком. Должен быть уникальным в течении всего периода работы с EasyPay
    sumчисло больше нулясумма в белорусских рублях
    mer_no6 алфавитно-цифровых символов вида okXXXX, где X – число от 0 до 9номер Поставщика в EasyPay. Выдается Администратором EasyPay при регистрации
    card8 цифридентификатор электронного кошелька EasyPay
    purch_dateГГГГ-ММ-ДД ЧЧ:ММ:ССдата и время оплаты счета
    notify_signature32 алфавитно-цифровых символовэлектронная подпись электронного счета
    xml_dataОт 0 до 64 килобайта текстовой информации в произвольной формедополнительный XML или другие текстовые данные

    При формировании реестра платежей за предыдущие сутки создается XML-документ, который передается в поле ep_notify_register:

    <?xml version="1.0" encoding="windows-1251"?>
    <easypay function="ep_notify_register" date="2006-09-11">
    	<invoices count="2" total_sum="300.00">
    		<invoice>
    			<order_mer_code>1000</order_mer_code>
    			<sum>100.00</sum>
    			<mer_no>ok6666</mer_no>
    			<card>00539900</card>
    			<purch_date>2006-09-11 22:45:21</purch_date>
    			<xml_data>text</xml_data>
    		</invoice>
    		<invoice>
    			<order_mer_code>1001</order_mer_code>
    			<sum>200.00</sum>
    			<mer_no>ok6666</mer_no>
    			<card>00539900</card>
    			<purch_date>2006-09-11 21:44:20</purch_date>
    			<xml_data>text</xml_data>
    		</invoice>
    	</invoices>
    </easypay>
    
    Формат электронной подписи
    В случае подтверждения счета, электронная подпись формируется с участием полей order_mer_code, sum, mer_no, card, purch_date, web_key, следующих в указанном порядке по алгоритму:

    notify_signature = md5 (order_mer_code . sum . mer_no . card . purch_date . web_key)

    При получении уведомления Поставщик проверяет подлинность этого сообщения по его электронной подписи.

    Пример на PHP обработчика уведомлений

    <?php
    /* 
    	Пример на PHP обработчика одиночных уведомлений (для реестра платежей аналогично)
    	Принимает и логирует уведомления EasyPay, но ничего с ними не делает
    	Поставщик осуществляет обработку уведомлений 
    	в соответствии с особенностями своей работы
    */
    
    $logfilepath	= '/test/logs/notify.log'; //путь к файлу логирования
    $web_key	= 'dh48djklhgl5893j'; //ключ, участвующий в электронной подписи сообщения 
    
    //Если у Вас нет ключа, то обратитесь в службу технической поддержки EasyPay
    
    $post_params = array (
    	'order_mer_code' => 
    		isset($_POST['order_mer_code']) ? $_POST['order_mer_code'] : '',	
    	'sum' => 
    		isset($_POST['sum']) ? $_POST['sum'] : '',	
    	'mer_no' => 
    		isset($_POST['mer_no']) ? $_POST['mer_no'] : '',	
    	'card' => 
    		isset($_POST['card']) ? $_POST['card'] : '',	
    	'purch_date' => 
    		isset($_POST['purch_date']) ? $_POST['purch_date'] : '',	
    	'notify_signature' => 
    		isset($_POST['notify_signature']) ? $_POST['notify_signature'] : '',
    	'xml_data' => 
    		isset($_POST['xml_data']) ? $_POST['xml_data'] : '',	
    );
    
    main ($logfilepath, $web_key, $post_params);
    
    function main($logfilepath, $web_key, $post_params) {
    	// пример обработки ежесуточного реестра платежей
    	if (isset($_POST['ep_notify_register'])) { // обработка реестра платежей
    		$processed = ProcessDailyNotify($_POST['ep_notify_register']);
    		if ($processed) { //реестр обработан
    			$status = 'OK | the register is processed'; // статус обработки
    			header("HTTP/1.0 200 OK"); // генерация HTTP-заголовка
    			print $status; // формирование контента
    		} else { //реестр не обработан
    			$status = 'FAILED | the register is not processed'; 
    			header("HTTP/1.0 400 Bad Request");
    			print $status;
    		}
    	} else { // обработка уведомления
    		//вычисляем электронную подпись и сравниваем с переданной
    		$notify_signature = CreateAuthorizationKey ($web_key, $post_params);
    		if($notify_signature == $post_params['notify_signature']) {
    			//осуществляем обработку уведомления и логирование как пример
    			$processed = ProcessNotify($post_params);
    			if ($processed) { //уведомление обработано
    				$status = 'OK | the notice is processed'; //статус обр.
    				header("HTTP/1.0 200 OK"); // генерация HTTP-заголовка
    				print $status; // формирование контента
    			} else { //уведомление не обработано
    				$status = 'FAILED | the notice is not processed'; 
    				header("HTTP/1.0 400 Bad Request");
    				print $status;
    			}
    		} else { //неверная электронная подпись
    			$status = 'FAILED | incorrect digital signature'; 
    			header("HTTP/1.0 400 Bad Request");
    			print $status;
    		}
    		//подготовка параметров для логирования
    		$params_line = '';
    		foreach ($post_params as $key=>$value) {
    			$params_line .= "$key=$value; ";
    		}
    		CreateLog($status, $params_line); //логирование
    	}
    }
    
    function CreateAuthorizationKey ($web_key, $post_params) {//функция вычисления эл. подписи
    	// правило вычисления: 
    	// notify_signature = md5(order_mer_code. sum. mer_no. card. purch_date. web_key) 
    	
    	$hash = md5($post_params['order_mer_code'].$post_params['sum'].
    	$post_params['mer_no'].$post_params['card'].$post_params['purch_date'].$web_key);
    	
    	return $hash;
    }
    
    function ProcessNotify($post_params) { // функция реализует логику обработки уведомлений
    	// Поставщик осуществляет обработку уведомлений
    	// в соответствии с особенностями своей работы
    	// обработка xml_data
    	// дополнительная проверка оплаты счета через SOAP для безопасности
    	$soap_check = SOAPIsInvoicePaid($post_params['order_mer_code']);
    	// 1 - уведомление обработано, 0 - уведомление не обработано
    	return 1;
    }
    
    fucntion SOAPIsInvoicePaid($order_mer_code) { //функция проверки оплаты счета через SOAP
    	// Поставщик дополнительно осуществляет проверку оплаты счёта по SOAP
    	// функцией EP_IsInvoicePaid
    	// https://ssl.easypay.by/soap/
    	// 1 - счет оплачен, 0 - счет не оплачен
    	return 1;
    }
    
    function ProcessDailyNotify($post_params) { // функция реализует логику обработки реестра
    	// Поставщик осуществляет обработку реестра
    	// в соответствии с особенностями своей работы
    	// 1 - ежесуточный реестр обработан, 0 - не обработан
    	return 1;
    }
    
    function CreateLog ($status, $request) { //функция добавления записи в логфайл
    	global $logfilepath;
    	$date = date("d.m.Y H:i:s");
    	$str = $date."\t".$status."\n\t"."ORDER_INFORMATION: ".$request."\n";
    	$log = fopen($logfilepath, 'a');
    	if($log) {
    		fwrite($log, $str);
    		fclose($log);
    	}
    }
    
    ?>
    

    Пример отправки уведомления

    Поставщик может проверить работу обработчика уведомлений на своем сайте, отправив тестовое сообщение. Для этого необходимо указать реквизиты тестового счета с его электронной подписью (в примере используется web_key = dh48djklhgl5893j) и реальный адрес (URL) обработчика.
    Реквизиты тестового счета и его электронная подпись
    Номер электронного счета, order_mer_code
    Сумма в рублях, sum
    Номер Поставщика в EasyPay, mer_no
    Номер электронного кошелька EasyPay, card
    Дата и время оплаты счета, purch_date
    Электронная подпись счета, notify_signature
    Отправка уведомления
    Адрес (URL) для отправки уведомления