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

Протокол взаимодействия


Общие сведения

Для успешной работы программных модулей и обеспечения безопасного приема платежей на хостинге сайта Поставщика должны быть установлены PHP или Perl (с модулем Digest::MD5). При выписке счетов для подписи заказа используется ключ web-key. Персональный ключ передается Поставщику после подписания договора. Автоматизацию некоторых операций (выписка счетов, отмена оплаты, получение списка оплаченных счетов и др.) можно реализовать через функции взаимодействия по протоколу SOAP. Это значительно упрощает учет оплат во внутреннем биллинге Поставщика. Процесс проведения платежа начинается с оформления заказа Покупателем на сайте Поставщика с последующей передачей информации на сайт EasyPay, где и происходит окончательное формирование и оплата счета. Покупатель заполняет специальную форму с параметрами заказа (подписанными секретным ключом) и для совершения оплаты перенаправляется на сайт EasyPay.

Оформления заказа и оплата

Процесс оформления заказа и оплата происходит по следующей схеме.

  1. Покупатель на сайте Поставщика выбирает товар или услугу, которую он хочет оплатить, заполняет необходимые для оформления заказа данные (ФИО, телефон, e-mail и т.д.).
  2. Там же Покупатель выбирает способ оплаты (электронные деньги, банковская карта или ЕРИП).
  3. Сайт Поставщика перенаправляет Покупателя на специальную страницу сайта EasyPay, где на основании информации формы заказа формируется счет на оплату. Подлинность счета подтверждается электронной подписью.
  4. В зависимости от выбранного способа оплаты Покупатель:

    - авторизуется на сайте с реквизитами своего кошелька (при оплате электронными деньгами);

    - перенаправляется на сайт банка (при оплате банковской картой);

    При необходимости предусмотрена возможность возврата Покупателя на сайт Поставщика.

  5. Статус выставленного счета контролируется Поставщиком через Административный интерфейс или посредством Уведомления об оплатах.

В границах определенного периода, при оплате электронными деньгами, Поставщик может вернуть оплаченные средства в кошелек Покупателя, по истечении этого времени деньги автоматически отправляются на банковский счет Поставщика (за вычетом комиссии). Длительность Периода Блокирования Поставщик выбирает самостоятельно. При оплате через ЕРИП или банковской картой (Visa, MasterCard) возврат денежных средств невозможен. В отдельных случаях существует возможность отмены выписанного счета или уменьшения его суммы.

Реализация

Для формирования заказа Поставщик на своем сайте создает форму с набором необходимых полей для его описания и отправляет эту форму POST-запросом на адрес: https://ssl.easypay.by/weborder/.

Запрос должен содержать набор обязательных параметров:

  • номер,
  • название,
  • описание,
  • сумму заказа.
  • Подлинность электронного счета гарантируется электронной подписью вида:

    EP_Hash = md5 (EP_MerNo . web_key . EP_OrderNo . EP_Sum), где web_key – ключ, в запросе не передается.

    Для возврата Покупателя на сайт Поставщика после оплаты используются дополнительные параметры: EP_Success_URL и EP_Cancel_URL (адреса возврата в случае успешной и не успешной операции). Эти адреса Поставщик передает вместе с другими полями POST-запроса. В случае корректного формирования счета к адресу возврата добавляется номер счета (EP_OrderNo), который передается на сайт Поставщика посредством GET-запроса.

    Адреса возврата используются Поставщиком для дополнительного информирования Покупателя на своем сайте о статусе оплаты счета, но не являются основанием для предоставления товара или услуги. Товар или услуга предоставляется Покупателю только после оплаты им счета.

    Контролировать оплату можно через административный интерфейс Поставщика или посредством Уведомления об оплатах.

    Для отладки и настройки программного обеспечения возможно формирование счетов в отладочном режиме (EP_Debug = 1). В этом случае отображаются все передаваемые в запросах поля, в том числе скрытые комментарии и сообщения об ошибках (например, при некорректном формировании запроса). При этом осуществляется реальная выписка счетов и оплата. После завершения настройки и тестирования отладочный режим необходимо отключить.

    Подключение к АИС "Расчет" (ЕРИП)

    Для подключения к АИС "Расчет" (ЕРИП) Поставщику необходимо дополнительно к основным параметрам передавать параметр EP_PayType=PT_ERIP, а также передавать и корректно обрабатывать адреса возврата EP_Success_URL и EP_Cancel_URL. В случае оплаты через ЕРИП системой EasyPay к адресам возврата автоматически добавляются параметры EP_OrderNo=xxx и EP_PayType=PT_ERIP, где xxx - номер зарегистрированного счета. Поставщик получает из URL и отображает данный реквизит (номер счета) на своем сайте.

    Структура запроса

    Поля, применяемые в запросах (рабочая кодировка в системе windows-1251):

    Название полейФормат полейОписание полей
    EP_MerNo6 алфавитно-цифровых символов вида okXXXX, где X – число от 0 до 9номер Поставщика в EasyPay. Выдается после подписания договоров
    EP_OrderNoот 1 до 20 алфавитно-цифровых символов
    Допускаются буквы, цифры, а также символы .-_
    уникальный номер электронного счета. Формируется Поставщиком. Номер должен быть уникальным в течение всего периода работы с EasyPay
    EP_Sumчисло больше нуля сумма в белорусских рублях
    разделитель ,. или отсутствует
    EP_Expiresчисло от 1 до 30, если период задан в днях или от 600 до 3600*24, если период задан в секундахвремя действительности счета в днях
    EP_Commentпроизвольное число (но не более 50) алфавитно-цифровых символов, кроме "<" и ">"
    Допускаются буквы, цифры, а также символы .,-_()+=;:?!@#№
    краткий комментарий счета. Формируется Поставщиком
    EP_OrderInfoпроизвольное число, (но не более 2000) алфавитно-цифровых символов, кроме "<" и ">"
    Допускаются буквы, цифры, а также символы .,-_()+=;:?!@#№$&*[]"'`/|\
    подробный комментарий счета. Формируется Поставщиком
    EP_Hash32 алфавитно-цифровых символовэлектронная подпись счета для подтверждения его подлинности
    EP_Success_URLпроизвольное число алфавитно-цифровых символов (URL)адрес, на который возвращается Покупатель в случае успешной оплаты, обязательный параметр при подключении к АИС "Расчет" (ЕРИП)не является основанием для предоставления товара или услуги
    EP_Cancel_URLпроизвольное число алфавитно-цифровых символов (URL)адрес, на который возвращается Покупатель в случае неуспешной оплаты, обязательный параметр при подключении к АИС "Расчет" (ЕРИП)
    EP_URL_Typeget, linkтип обработки адресов возврата EP_Success_URL и EP_Cancel_URL. Если значение поля get или оно отсутствует, то к адресам возврата добавляется номер счета (EP_OrderNo), который передается на сайт Поставщика GET-запросом. Если значение link, то адреса возврата не обрабатываются, необязательный параметр
    EP_Debugцелое число (0, 1)режим отладки (0 или отсутствует – отладочный режим отключен, 1 – включен), необязательный параметр
    EP_Encodingназвание кодировки (utf-8, koi8-r)кодировка полей запроса. В случае отсутствия используется кодировка windows-1251, необязательный параметр
    EP_XmlОт 0 до 64 килобайта текстовой информации в произвольной формедополнительный XML или другие текстовые данные, необязательный параметр
    EP_PayTypePT_ERIPобязательный параметр только при подключении к АИС "Расчет" (ЕРИП)

    Примеры

    Формирование счета
    Поля для EasyPay, должны быть заполнены в соответствии с данными счета
    Номер счета
    Уникальный номер электронного счета. Формируется Поставщиком
    Название заказа
    При отсутствии формируется по формуле "Заказ от Поставщика [Название Поставщика]"
    Описание заказа
    При отсутствии формируется по полям не относящимся к EasyPay (CustName, CustAddr, CustEMail, OrderDetails)
    Сумма в рублях
    Cумма оплаты в белорусских рублях
    Скрытые поля, автоматически заполняются регистрационными данными Поставщика перед передачей их в EasyPay
    Номер Поставщика в EasyPay
    Выдается после подписания договоров
    Время действительности счета в днях
    Указывается в настройках
    Электронная подпись заказа
    Формируется на основе данных заказа и авторизационного ключа (web_key)
    URL возврата (успех), необязательный параметр
    Адрес, на который возвращается Покупатель в случае успешной оплаты
    URL возврата (неуспех), необязательный параметр
    Адрес, на который возвращается Покупатель в случае неуспешной оплаты
    Режим отладки, необязательный параметр
    При включении режима отладки отображаются все переданные в EasyPay данные
    Поля заказа, используемые Поставщиком для собственных нужд, в EasyPay не передаются
    Ф.И.О.
    Адрес доставки
    E-mail
    Дополнительная информация
    Пример скрипта на PHP для формирования счета

    Для настройки сайта в тестовом режиме необходимо использовать тестовый адрес https://ssl.easypay.by/test/client_weborder.php, а также произвольные EP_MerNo, web-key, подробнее.

    <?php 
    /*
    	Пример на PHP формирования счета Поставщиком 
    	для оплаты в EasyPay (см. https://ssl.easypay.by/light/)
    	1. Заполняем необходимые для EasyPay поля с описанием товара (услуги)
    	2. При необходимости - дополнительные данные для Поставщика (ФИО, адрес и т. д.)
    	3. Вычисляем электронную подпись заказа
    	4. Перенаправляем пользователя на сайт EasyPay для оплаты
    */
    
    $EP_Params = array ( //конфигурационные параметры Поставщика
    	'web_key'	=>	'XXXXXXXXXXXXXXXXX', //ключ для подписи счетов 
    	'URL'		=>	'https://ssl.easypay.by/weborder/', // POST-запросы
    
    	'EP_MerNo'	=>	'okXXXX', //номер Поставщика в EasyPay
    	'EP_OrderNo'	=>	time().posix_getpid(), //уникальный номер счета
    	'EP_Sum'	=>	'12000', //сумма в белорусских рублях
    	'EP_Expires'	=>	'2', //время действительности счета в днях
    	'EP_Comment'	=>	'Покупка тренажера', //краткий комментарий
    	'EP_OrderInfo'	=>	'Велотренажер Кетлер М-25', //подробный комментарий
    	'EP_Success_URL'=>	'http://mytestshop.by/success/', //URL успех
    	'EP_Cancel_URL'	=>	'http://mytestshop.by/cancel/', //URL неуспех
    	'EP_Debug'	=>	'0', //отладочный режим, необязательный параметр
    );
    
    main ($EP_Params); 
    
    function main ($EP_Params) {
    	$EP_Hash = CreateAuthorizationKey ($EP_Params);
    	$html = 
    	
    	'<html>
    	<head>
    	<meta http-equiv="Content-Type" content="text/html; charset=windows-1251" />
    	<title>Магазин "Спортивные товары"</title>
    	</head>
    	<body>
    
    	<form action="'.$EP_Params['URL'].'" method="post" target="_blank">
    	<input type="hidden" name="EP_MerNo" value="'.$EP_Params['EP_MerNo'].'" />
    	<input type="hidden" name="EP_Expires" value="'.$EP_Params['EP_Expires'].'" />
    	<input type="hidden" name="EP_Hash" value="'.$EP_Hash.'" />
    	<input type="hidden" name="EP_Success_URL" 
    		value="'.$EP_Params['EP_Success_URL'].'" />
    	<input type="hidden" name="EP_Cancel_URL" 
    		value="'.$EP_Params['EP_Cancel_URL'].'" />
    	<input type="hidden" name="EP_Debug" value="'.$EP_Params['EP_Debug'].'" />
    
    	<table cellpadding="3" style="text-align:right">
    	<tr>
    		<td>Номер счета</td>
    		<td><input type="text" name="EP_OrderNo" 
    		value="'.$EP_Params['EP_OrderNo'].'" readonly /></td>
    	</tr>
    	<tr>
    		<td>Название заказа</td>
    		<td><input type="text" name="EP_Comment" 
    		value="'.$EP_Params['EP_Comment'].'" readonly /></td>
    	</tr>
    	<tr>
    		<td>Описание заказа</td>
    		<td><input type="text" name="EP_OrderInfo" 
    		value="'.$EP_Params['EP_OrderInfo'].'" readonly /></td> 
    	</tr>
    	<tr>
    		<td>Сумма в рублях</td>
    		<td><input type="text" name="EP_Sum" 
    		value="'.$EP_Params['EP_Sum'].'" readonly /></td>
    	</tr>
    	<tr>
    		<td colspan="2"><hr /></td>
    	</tr>
    	<tr>
    		<td>Ф.И.О.</td>
    		<td><input type="text" name="CustName" /></td>
    	</tr>
    	<tr>
    		<td>Адрес доставки</td>
    		<td><input type="text" name="CustAddr" /></td>
    	</tr>
    	<tr>
    		<td>E-mail</td>
    		<td><input type="text" name="CustEMail" /></td>
    	</tr>
    	<tr>
    		<td>Дополнительная информация</td>
    		<td><input type="text" name="OrderDetails" /></td>
    	</tr>
    	<tr>
    		<td colspan="2"><hr /></td>
    	</tr>
    	<tr>
    		<td></td>
    		<td><input type="submit" value="Оплатить счет" /></td>
    	</tr>
    	</table>
    	
    	</form>
    	
    	</body>
    	</html>';
    	
    	print $html;
    }
    
    function CreateAuthorizationKey ($EP_Params) { //функция вычисления электронной подписи
    	// правило вычисления: EP_Hash  = md5 (EP_MerNo . web_key . EP_OrderNo . EP_Sum) 
    	$hash = md5($EP_Params['EP_MerNo'].$EP_Params['web_key'].
    		$EP_Params['EP_OrderNo'].$EP_Params['EP_Sum']);
    	return $hash;
    }
    
    ?>