SOAP (Simple Object Access Protocol — простой протокол доступа к объектам) - используется для вызова функций и обмена произвольными сообщениями в формате XML.
Адрес пароли доступа к SOAP-серверу EasyPay Поставщик получает после подписания договоров.
Для отладки и тестирования взаимодействия можно воспользоваться тестовыми интерфейсами.
После заключения договоров для интеграции интернет-ресурса в систему EasyPay Поставщик производит предварительную настройку параметров своего сайта.
Процессинговый центр предоставляет следующие данные для идентификации:
Название полей | Формат полей | Описание полей |
---|---|---|
mer_no | 6 алфавитно-цифровых символов вида okXXXX, где X – число от 0 до 9 | номер Поставщика в EasyPay. Выдается Администратором EasyPay при регистрации |
pass | от 8 до 25 алфавитно-цифровых символов | пароль Поставщика в EasyPay. Выдается Администратором EasyPay при регистрации |
Название полей | Формат полей | Описание полей |
---|---|---|
mer_no | 6 алфавитно-цифровых символов вида okXXXX, где X – число от 0 до 9 | номер Поставщика в EasyPay. Выдается Администратором EasyPay при регистрации |
pass | от 8 до 25 алфавитно-цифровых символов | пароль Поставщика в EasyPay. Выдается Администратором EasyPay при регистрации |
order (order_mer_code) | от 1 до 20 алфавитно-цифровых символов.
Допускаются буквы, цифры, а также символы .-_ | уникальный номер электронного счета. Формируется Поставщиком. Номер должен быть уникальным в течение всего периода работы с EasyPay |
sum | число больше нуля |
сумма в белорусских рублях
разделитель ,. или отсутствует |
exp | число от 1 до 30, если период задан в днях или от 600 до 3600*24, если период задан в секундах | время действительности счета в днях |
card | PT_ERIP, PT_EPOS | способ оплаты |
comment | произвольное число (но не более 50) алфавитно-цифровых символов кроме "<" и ">".
Допускаются буквы, цифры, а также символы .,-_()+=;:?!@#№ | краткий комментарий счета. Формируется Поставщиком |
cancel_comment | произвольное число (но не более 150) алфавитно-цифровых символов кроме "<" и ">".
Допускаются буквы, цифры, а также символы .,-_()+=;:?@#№$&*[]"'`/|\ | комментарий к отмененному счету. Формируется Поставщиком |
info | произвольное число, (но не более 2000) алфавитно-цифровых символов кроме "<" и ">", возможны переводы строк.
Допускаются буквы, цифры, а также символы .,-_()+=;:?!@#№$&*[]"'`/|\ | подробный комментарий счета. Формируется Поставщиком |
xml | От 0 до 64 килобайта текстовой информации в произвольной форме | дополнительный XML или другие текстовые данные |
message | произвольное число алфавитно-цифровых символов кроме "<" и ">" | комментарий на code ошибки от сервера на русском языке. Формируется сервером EasyPay, поясняет код ошибки |
invoices | структура, в которой содержатся поля, описывающие счета: order_mer_code - номер счета, purch_date - дата и время оплаты счета | |
invoices_ext | Invoices_ext – структура описания счетов с дополнительными полями: order – номер счета, purch_date – дата и время оплаты счета, sum – сумма в белорусских рублях, exp – дата окончания времени жизни счета, card – идентификатор EasyPay, PT_CARD для банковских карт, PT_ERIP для счетов ЕРИП, comment – краткий комментарий счета, info – полный комментарий счета, xml – дополнительное описание счета в произвольной форме |
В случае успешного выполнения операции для всех функций, код возврата code = 200, в противном случае иной код. В случае ошибки цифровой код сопровождается текстовым сообщением об ошибке.
Рабочая кодировка в системе Windows-1251. Все принимаемые и передаваемые данные, комментарии и сообщения об ошибках должны быть в этой кодировке.
Обратите внимание: при обращении к функциям через SOAP код ответа сервера EasyPay - code и сообщение, его поясняющее - message, находятся в поле status.
(code, message) = EP_CreateInvoice(mer_no, pass, order, sum, exp, card, comment, info, xml)
Подробный список способов и мест оплаты, а также другую интересующую вас информацию вы можете найти на сайте системы "Расчет".
При оплате банковской картой оплата производится на сайте банка эмитента.
Для проверки счета на предмет оплаты рекомендуется использовать одну из функций проверки или получения списка оплаченных счетов. Интервал между проверками оплаченных счетов - не менее 5 минут.
При получении списка оплаченных счетов (функции EP_GetPaidInvoices, EP_GetPaidInvoicesExt) выдаются не более 100 счетов, оплаченных после даты оплаты счета order, указанного в качестве параметра. Если такого счета нет в системе, то выдаются не более 100 первых оплаченных счетов.
Таким образом, для получения списка оплаченных счетов необходимо при первом вызове функции передавать в качестве параметра order='' или несуществующий номер счета, а при последующих вызовах последний номер счета order, полученный на предыдущем шаге.
(code, message, invoices) = EP_GetPaidInvoices(mer_no, pass, order)
(code, message, invoices_ext) = EP_GetPaidInvoicesExt(mer_no, pass, order)
Рекомендуется использовать эту функцию как дополнительную к списку: для ускорения получения оплаты счета по запросу Покупателя на сайте Поставщика.
(code, message, xml) = EP_IsInvoicePaid(mer_no, pass, order)
code = 200 – счет оплачен
code = 211 – счет не оплачен
code = 503 - неуникальный или несуществующий электронный счет-заказ. Проверьте номер счета!
code = 506 – счет-заказ просрочен
code = 517 – счет-заказ отменен
Предназначен для отмены операции по инициативе Поставщика в случае невозможности ее завершения.
(code, message) = EP_IsInvoicePaid(mer_no, pass, order)
Данная функция используется как для проверки оплаты счета, так и для проверки наличия счета в системе.
(code, message) = EP_DecreaseInvoice(mer_no, pass, order, sum)
В некоторых случаях возникает необходимость изменить сумму счета после оплаты его Покупателем. В EasyPay существует возможность уменьшения суммы оплаченного счета. Для включения такой возможности Поставщику необходимо обратиться в службу поддержки EasyPay.
В случае успешно проведенной операции возвращается code = 200 или code = 211 - счет не оплачен. Ниже приведен список некоторых встречающихся кодов:
code = 200 - успешное выполнение операции
code = 211 - счет не оплачен
code = 503 - неуникальный или несуществующий электронный счет-заказ. Проверьте номер счета!
code = 560 - отмена платежа не разрешена
code = 1004 - услуга запрещена
XML-пакеты формируются неявно при взаимодействии с SOAP-сервером EasyPay при вызове функций.
Рассмотрим XML-запрос и XML-ответ на примере функции:
(code, message) = EP_IsInvoicePaid(mer_no, pass, order)
<?xml version="1.0" encoding="UTF-8"?> <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://easypay.by/"> <SOAP-ENV:Body> <ns1:EP_IsInvoicePaid> <ns1:mer_no>ok****</ns1:mer_no> <ns1:pass>******</ns1:pass> <ns1:order>1170338164</ns1:order> </ns1:EP_IsInvoicePaid> </SOAP-ENV:Body> </SOAP-ENV:Envelope>
<?xml version="1.0" encoding="UTF-8"?> <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns1="http://easypay.by/"> <SOAP-ENV:Body> <ns1:EP_IsInvoicePaidResponse> <ns1:status> <ns1:code>200</ns1:code> <ns1:message> </ns1:message> </ns1:status> </ns1:EP_IsInvoicePaidResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>
<?php /* client.php требования: PHP с расширением SOAP SOAP-клиент для демонстрации обращения к SOAP-серверу EasyPay. Для каждого конкретного Поставщика должна быть своя реализация SOAP-клиента в соответствии с внутренней логикой работы и схемой взаимодействия с EasyPay с соответствующей обработкой ошибок и исключительных ситуаций. При использовании https-соединения в конструкторе клиента при необходимости дополнительно указывать путь к сертификату и пароль на ключ сертификата */ //--------------------------------ПАРАМЕТРЫ---------------------------------- $wsdl = 'https://ssl.easypay.by/****'; //адрес SOAP-сервера $encoding = 'windows-1251'; //кодировка счета (кодировка на сайте Поставщика) //массив параметров для вызова функции выписки счета (EP_CreateInvoice) $params_EP_CreateInvoice = array( 'mer_no' =>'ok****', //тестовый Поставщик 'pass' =>'*****', //пароль на тестовый Поставщик 'order' =>'4000', //номер счета 'sum' =>'100', //сумма в белорусских рублях 'exp' =>'4', //время жизни счета 'card' =>'PT_ERIP', //ЕРИП 'comment' =>substr('Комментарий счета', 0, 50), //комментарий счета (до 50 симв.) 'info' =>substr('Информация о счете', 0 , 2000), //подробный ком. (до 2000 с.) 'xml' =>'<xml>Это xml-данные</xml>', //xml-данные ); //параметры для вызова функции получения оплаченных счетов (EP_GetPaidInvoices) $params_EP_GetPaidInvoices = array( 'mer_no' =>'ok****', //тестовый Поставщик 'pass' =>'*****', //пароль на тестовый Поставщик 'order' =>'0', //номер счета. 0 - для получения первых 100 оплаченных счетов. ); //--------------------------------------------------------------------------- main(); function main () { global $wsdl, $encoding, $params_EP_CreateInvoice, $params_EP_GetPaidInvoices; //создание клиента $client = new SoapClient($wsdl, array('trace' => 1, 'encoding' => $encoding)); //может возникнуть исключение SoapFault при неявном формировании //входных и выходных xml-пакетов try { //вызов функции EP_CreateInvoice $answer = $client->EP_CreateInvoice($params_EP_CreateInvoice); } catch (SoapFault $fault) { print "ExeptionIsCatchedByUser!<br>faultcode: $fault->faultcode; faultstring: $fault->faultstring<br>"; } print_r ($answer); //отображение структуры ответа сервера /* структура ответа сервера stdClass Object ( [status] => stdClass Object ( [code] => 200 [message] => ) ) */ /* обращаться к полям структуры можно так: print $answer->status->code; //код ответа сервера EasyPay print $answer->status->message; //сообщение, поясняющее код возвращаемый объект можно преобразовать в массив с помощью (array) */ //может возникнуть исключение SoapFault при неявном формировании //входных и выходных xml-пакетов try { //вызов функции EP_CreateInvoice $answer = $client->EP_GetPaidInvoices($params_EP_GetPaidInvoices); } catch (SoapFault $fault) { print "ExeptionIsCatchedByUser!<br>faultcode: $fault->faultcode; faultstring: $fault->faultstring<br>"; } //массив оплаченных счетов. Количество счетов = количеству элементов print_r ((array)$answer->invoices); /* вид массива оплаченных счетов. В этом примере есть 3 оплаченных счета Array ( [0] => stdClass Object ( [order_mer_code] => ad_1200407111 [purch_date] => 2008-01-15 16:25:50 ) [1] => stdClass Object ( [order_mer_code] => ad_1200567652 [purch_date] => 2008-01-17 13:01:18 ) [2] => stdClass Object ( [order_mer_code] => 4000 [purch_date] => 2008-01-18 17:18:53 ) ) */ //массив полей первого счета в системе (если он есть) массива счетов print_r ((array)$answer->invoices[0]); /* вид массива полей оплаченного счета Array ( [order_mer_code] => ad_1200407111 [purch_date] => 2008-01-15 16:25:50 ) */ //Остальные функции вызываются аналогичным образом //получить структуру неявно формируемого xml-пакета можно так //отображение xml-пакета для анализа и отладки (запрос) $request = ($client->__getLastRequest()); //для более наглядного отображения и анализа xml-пакета $request = preg_replace("/></", ">\n<", $request); //отображение xml-пакета для анализа и отладки (ответ) $response = ($client->__getLastResponse()); //для более наглядного отображения и анализа xml-пакета $response = preg_replace("/></", ">\n<", $response); print "<pre>\n"; print "Запрос:\n".$request."\n"; print "Ответ:\n".$response."\n"; print "</pre>"; } ?>