Для успешной работы программных модулей и обеспечения безопасного приема платежей на хостинге сайта Поставщика должен быть установлен например PHP. При выписке счетов для подписи заказа используется ключ web_key. Персональный ключ передается Поставщику после подписания договора.
Автоматизацию некоторых операций (выписка счетов, отмена оплаты, получение списка оплаченных счетов и др.) можно реализовать через функции взаимодействия по протоколу SOAP. Это значительно упрощает учет оплат во внутреннем биллинге Поставщика.
Процесс проведения платежа начинается с оформления заказа Покупателем на сайте Поставщика с последующей передачей информации на сайт EasyPay, где и происходит окончательное формирование и оплата счета. Покупатель заполняет специальную форму с параметрами заказа (подписанными секретным ключом) и для совершения оплаты перенаправляется на сайт EasyPay.
Процесс оформления заказа и оплата происходит по следующей схеме.
- перенаправляется на сайт банка (при оплате банковской картой). При необходимости предусмотрена возможность возврата Покупателя на сайт Поставщика.
- перенаправляяется на страницу сайта Поставщика с номером заказа в ЕРИП (при оплате через ЕРИП);
Для формирования заказа Поставщик на своем сайте создает форму с набором необходимых полей для его описания и отправляет эту форму POST-запросом на адрес: https://ssl.easypay.by/weborder/.
Запрос должен содержать набор обязательных параметров:
Подлинность электронного счета гарантируется электронной подписью вида:
EP_Hash = md5 (EP_MerNo . web_key . EP_OrderNo . EP_Sum), где web_key – ключ, в запросе не передается.
Для возврата Покупателя на сайт Поставщика после операции (оплаты банковской картой или выписки счета ЕРИП, E-POS) используются дополнительные параметры: 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_MerNo | 6 алфавитно-цифровых символов вида 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_Hash | 32 алфавитно-цифровых символов | электронная подпись счета для подтверждения его подлинности |
EP_Success_URL | произвольное число алфавитно-цифровых символов (URL) | адрес, на который возвращается Покупатель в случае успешной оплаты банковской картой (или выписки счета ЕРИП, E-POS), не является основанием для предоставления товара или услуги |
EP_Cancel_URL | произвольное число алфавитно-цифровых символов (URL) | адрес, на который возвращается Покупатель в случае неуспешной оплаты банковской картой (или выписки счета ЕРИП, E-POS) |
EP_URL_Type | get, 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_PayType | PT_ERIP | обязательный параметр только при подключении к АИС "Расчет" (ЕРИП) c настройкой показа номера зарегистрированного счета на сайте Поставщика |
Для настройки сайта в тестовом режиме необходимо использовать тестовый адрес 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' => '12.50', //сумма в белорусских рублях '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; } ?>