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

Использование функций взаимодействия по протоколу SOAP


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

SOAP (Simple Object Access Protocol — простой протокол доступа к объектам) - используется для вызова функций и обмена произвольными сообщениями в формате XML.

Адрес пароли доступа к SOAP-серверу EasyPay Поставщик получает после подписания договоров.

Для отладки и тестирования взаимодействия можно воспользоваться тестовыми интерфейсами.

Операции, используемые для работы с EasyPay:
1. Выставление счета Покупателю
2. Получение списка оплаченных Покупателями счетов
3. Вспомогательные операции (отправка сообщения Покупателю, отмена платежа и др.)
4. Перечисление средств со счета Поставщика в кошелек Покупателя

После заключения договоров для интеграции интернет-ресурса в систему EasyPay Поставщик производит предварительную настройку параметров своего сайта.

Процессинговый центр предоставляет следующие данные для идентификации:

Название полейФормат полейОписание полей
mer_no6 алфавитно-цифровых символов вида okXXXX, где X – число от 0 до 9номер Поставщика в EasyPay. Выдается Администратором EasyPay при регистрации
passот 8 до 25 алфавитно-цифровых символовпароль Поставщика в EasyPay. Выдается Администратором EasyPay при регистрации

Описание входных и выходных параметров функций

Название полейФормат полейОписание полей
mer_no6 алфавитно-цифровых символов вида 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, если период задан в секундахвремя действительности счета в днях
card8 цифридентификатор (номер) электронного кошелька EasyPay
commentпроизвольное число (но не более 50) алфавитно-цифровых символов кроме "<" и ">".
Допускаются буквы, цифры, а также символы .,-_()+=;:?!@#№
краткий комментарий счета. Формируется Поставщиком
cancel_commentпроизвольное число (но не более 150) алфавитно-цифровых символов кроме "<" и ">".
Допускаются буквы, цифры, а также символы .,-_()+=;:?@#№$&*[]"'`/|\
комментарий к отмененному счету. Формируется Поставщиком
infoпроизвольное число, (но не более 2000) алфавитно-цифровых символов кроме "<" и ">", возможны переводы строк.
Допускаются буквы, цифры, а также символы .,-_()+=;:?!@#№$&*[]"'`/|\
подробный комментарий счета. Формируется Поставщиком
subjectпроизвольное число (но не более 250) алфавитно-цифровых символов кроме "<" и ">".
Допускаются буквы, цифры, а также символы .,-_()+=;:?!@#№
заголовок сообщения Покупателю. Формируется Поставщиком
textпроизвольное число (но не более 10000) алфавитно-цифровых символов кроме "<" и ">", возможны переводы строк.
Допускаются буквы, цифры, а также символы .,-_()+=;:?!@#№$&*[]"'`/|\
текст сообщения Покупателю. Формируется Поставщиком
codeцелое числокод ответа от сервера EasyPay
messageпроизвольное число алфавитно-цифровых символов кроме "<" и ">"комментарий на code ошибки от сервера на русском языке. Формируется сервером EasyPay, поясняет код ошибки
xmlОт 0 до 64 килобайта текстовой информации в произвольной формедополнительный XML или другие текстовые данные
pay_idот 1 до 32 алфавитно-цифровых символов кроме "<" и ">".
Допускаются буквы, цифры, а также символы .-_
уникальный идентификатор платежа. Формируется Поставщиком
invoicesструктура, в которой содержатся поля, описывающие счета: order_mer_code - номер счета, purch_date - дата и время оплаты счета
invoices_extInvoices_ext – структура описания счетов с дополнительными полями: order – номер счета, purch_date – дата и время оплаты счета, sum – сумма в белорусских рублях, exp – дата окончания времени жизни счета, card – идентификатор (номер) электронного кошелька EasyPay или PT_ERIP для счетов ЕРИП, comment – краткий комментарий счета, info – полный комментарий счета, xml – дополнительное описание счета в произвольной форме

В случае успешного выполнения операции всех функций, код возврата code = 200, в противном случае code = 211. Обычно цифровой код сопровождается текстовым сообщением об ошибке.

Рабочая кодировка в системе Windows-1251. Все принимаемые и передаваемые данные, комментарии и сообщения об ошибках должны быть в этой кодировке. Внешний XML-обмен происходит в кодировке utf-8.

Обратите внимание: при обращении к функциям через SOAP код ответа сервера EasyPay - code и сообщение, его поясняющее - message, находятся в поле status.

Выписка счетов

Выписка счета (электронные деньги или банковские карты)

(code, message) = EP_CreateInvoice(mer_no, pass, order, sum, exp, card, comment, info, xml)

Выписка счета (ЕРИП)

(code, message) = EP_CreateInvoice(mer_no, pass, order, sum, exp, PT_ERIP, comment, info, xml)

Оплата заказа

При оплате электронными деньгами оплата заказа производится на сайте EasyPay. Здесь Покупатель совершает операцию посредством своего электронного кошелька на основании выставленного счета.

В случае оплаты банковской картой оплата производится на сайте банка эмитента.

Проверка оплаты счета

Для проверки счета на предмет оплаты рекомендуется использовать одну из функций проверки или получения списка оплаченных счетов. Интервал между проверками оплаченных счетов - не менее 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_CancelInvoice (mer_no, pass, order, cancel_comment)

Предназначен для отмены операции по инициативе Поставщика в случае невозможности ее завершения. Отмена возможна только для неоплаченного счета.

Отправка сообщения Покупателю

(code, message) = EP_SendMessage(mer_no, pass, order, card, subject, text)

Отправка сообщения Покупателю с указанием номера оплаченного счета - укажите order. Если требуется отправить сообщение, не привязанное к определенному счету, параметр order можно оставить пустым (order=''). Доступна только для Покупателей - владельцев электронных кошельков EasyPay.

Перевод денег в кошелек Покупателя от Поставщика

Данная функция используется, если Поставщик, оказывающий услуги, выполняет также роль Агента по распространению электронных денег, т.е. осуществляет перевод денег в кошелек Покупателя (настраивается Администратором EasyPay). Например, при выплате выигрышей (букмекерские конторы, лотереи).

Информация для Агентов по распространению электронных денег

Проверка наличия счета в системе

(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 = 306 - идентификатор (номер) электронного кошелька EasyPay содержит недопустимые символы
code = 501 - несуществующий идентификатор (номер) электронного кошелька EasyPay
code = 330 - сумма меньше 100 руб. Необходимо увеличить сумму для проведения операции
code = 30 - неверный формат переданных данных
code = 31 - ошибка соединения с сервером EasyPay
code = 32 - неверный формат ответа сервера EasyPay
code = 500 - неизвестная внутренняя ошибка. При возврате ошибки с кодом "500" обратитесь к Администратору

*При выставлении счетов Покупателям отображайте полученное сообщение об ошибке вместе с кодом (номером).

Схема взаимодействия Поставщика с Процессинговым центром

Пример xml-пакетов

XML-пакеты формируются неявно при взаимодействии с SOAP-сервером EasyPay при вызове функций.
Рассмотрим XML-запрос и XML-ответ на примере функции:

(code, message) = EP_IsInvoicePaid(mer_no, pass, order)

Xml-запрос:
<?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-ответ:
<?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>

Пример клиента на PHP5 с использованием библиотеки SOAP

<?php 
/*	client.php требования: PHP5 с расширением SOAP
	SOAP-клиент для демонстрации обращения к SOAP-серверу EasyPay.
	Для каждого конкретного Поставщика должна быть своя реализация SOAP-клиента 
	в соответствии с внутренней логикой работы и схемой взаимодействия с EasyPay
	с соответствующей обработкой ошибок и исключительных ситуаций.
	При использовании https-соединения в конструкторе клиента при необходимости
	дополнительно указывать путь к сертификату и пароль на ключ сертификата
*/

/*	Cписок доступных функции EasyPay 
	'EP_CreateInvoice',			
	'EP_IsInvoicePaid',			
	'EP_GetPaidInvoices',		
	'EP_SendMessage',			
	'EP_GetPaidInvoicesExt',	
	'EP_CheckCard',
	'EP_CreatePayment',	
	'EP_CheckPayment',
	'EP_CancelInvoice',			
	'EP_ConfirmInvoice',		
	'EP_MerchantBalance',
*/

//--------------------------------ПАРАМЕТРЫ----------------------------------
$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'      =>'00539959', //идентификатор (номер) электронного кошелька EasyPay
	'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>";
}

?>