domain.bybeseller.byshop.bykupika.by

ВЗАИМОДЕЙСТВИЕ ПО SOAP

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

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

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

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

Операции, используемые для работы с EasyPay:

  • Выставление счета Покупателю
  • Получение списка оплаченных Покупателями счетов
  • Вспомогательные операции (отмена платежа и др.)

После заключения договоров для интеграции интернет-ресурса в систему 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, если период задан в секундахвремя действительности счета в днях
cardPT_ERIP, PT_EPOSспособ оплаты
commentпроизвольное число (но не более 50) алфавитно-цифровых символов кроме "<" и ">".
Допускаются буквы, цифры, а также символы .,-_()+=;:?!@#№
краткий комментарий счета. Формируется Поставщиком
cancel_commentпроизвольное число (но не более 150) алфавитно-цифровых символов кроме "<" и ">".
Допускаются буквы, цифры, а также символы .,-_()+=;:?@#№$&*[]"'`/|\
комментарий к отмененному счету. Формируется Поставщиком
infoпроизвольное число, (но не более 2000) алфавитно-цифровых символов кроме "<" и ">", возможны переводы строк.
Допускаются буквы, цифры, а также символы .,-_()+=;:?!@#№$&*[]"'`/|\
подробный комментарий счета. Формируется Поставщиком
xmlОт 0 до 64 килобайта текстовой информации в произвольной формедополнительный XML или другие текстовые данные
messageпроизвольное число алфавитно-цифровых символов кроме "<" и ">"комментарий на code ошибки от сервера на русском языке. Формируется сервером EasyPay, поясняет код ошибки
invoicesструктура, в которой содержатся поля, описывающие счета: order_mer_code - номер счета, purch_date - дата и время оплаты счета
invoices_extInvoices_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_CancelInvoice (mer_no, pass, order, cancel_comment)

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

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

(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-пакетов

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>

						

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

Скопированно в буфер обмена
PHP


<?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>";
}

?>