Проверка осуществляется для того, чтобы удостовериться, что счёт и последующий платёж могут быть корректно обработаны на стороне Проекта.

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

Проекту необходимы:

• URL проверки идентификатора или заказа пользователя (указать в Технических настройках в Личном кабинете);
• Обработчик, способный принять и распознать параметры запроса от Системы и ответить так, как того ожидает Система.

Если проверка идентификатора после выставления счёта завершилась с ошибкой, то счёт выставлен не будет, а пользователь переадресуется на страницу ошибки платежа, указанную проектом с помощью параметра return_url_fail или в Технических настройках (если страница не указана - используется аналогичная на стороне Системы). На страницу ошибки платежа методом GET автоматически отправляется параметр err_msg со значением « Такого персонажа не существует» .

Параметры запроса от Системы в Проект

Система отсылает Проекту запрос на URL проверки идентификатора или заказа пользователя, указанный в Технических настройках в Личном кабинете.

• метод передачи - POST ;
• кодировка - UTF-8 .

Параметр	Описание параметра	Формат параметра	Обязательность параметра
userid	Идентификатор пользователя или заказа (равен значению параметра nickname в )	string(256)	Да
userid_extra	Дополнительные сведения, необходимые для совершения платежа или сбора статистики на стороне Проекта (равен значению параметра nick_extra )	string(500)	Нет
key	Контрольная подпись запроса. Формируется как хэш по алгоритму md5 от конкатенации следующих параметров: значение параметра userid , секретный ключ проекта	md5(0userid0секрет проекта)	Да
amount		0	Да
paymentid	Проверка check запроса. Принимает только нулевое значение (amount = 0)	0	Да
orderid	Идентификатор платежа в учётной системе Проекта (равен значению параметра order_id в )	varchar(64)	Нет

Параметры ответа Проекта

На запрос Системы от Проекта должен приходить ответ.

Для передачи параметров запроса используются следующие правила:

• формат - XML ;
• кодировка - UTF-8 .

Параметр	Описание параметра	Формат параметра	Обязательность параметра
code	Код ответа на запрос. YES - идентификатор существует. NO - идентификатор не существует	(регистрозависимый)	Да
comment	Расшифровка кода ответа на запрос. Примеры текста: не прошла валидация по параметру userid; не прошла валидация по параметру orderid; не прошла валидация по параметру key	string(400)	Нет

Пример ответа на запрос проверки идентификатора пользователя или заказа

YES

Пример минимального обработчика запросов Системы при проверке идентификатора пользователя или заказа

//Генерация ответа function sendResponse($status, $message = ""){ $response = ""."\n"; $response .= ""."\n"; $response .= "".$status.""."\n"; $response .= "".$message.""."\n"; $response .= ""; die($response); } //Проверка существования идентификатора пользователя или заказа function checkUser($userID){ $sql = "SELECT login FROM users WHERE usr_id = ".intval($userID); $query = mysql_query($sql); if(mysql_error()){ return FALSE; } if(mysql_num_rows($query) == 0){ return FALSE; } return TRUE; } $secretKey = "IT\"S_A_PROJECT_SECRET_WORD"; $projectHash = md5($_POST["amount"].$_POST["userid"].$_POST["paymentid"].$secretKey); if($projectHash != $_POST["key"]){ sendResponse("NO", "Контрольная подпись запроса неверна."); } if(floatval($_POST["amount"]) == 0 && intval($_POST["paymentid"]) == 0){ //Запрос на проверку идентификатора пользователя или заказа if(checkUser($_POST["userid"])){ sendResponse("YES", "Идентификатор существует"); } else{ sendResponse("NO", "Идентификатор не найден"); } }

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

Описание входных параметров

Входные данные: XML документ по схеме WS_ULIPZAPRID_2_311_11_04_0 2 _01_01.XSD

1. Описание выходных параметров

Выходные данные: XML документ по схемеWS_OTVVIPULXSD_2_311_14_04_02_01.XSD

или

Выходные данные: XML документ по схеме WS_ULIPOTVID_2_311_09_04_02_01.XSD

Параметры комплексного типа описаны в приложении «Описание общих структур данных» (в пунктах 10, 6, 9).

1. Коды возвратов

№	Код возврата	Описание кода возврата	Условия возникновения	Комментарий
1	01	Запрашиваемые сведения не найдены	Возникает при условии, что сведения о ЮЛ не найдены в ЕГРЮЛ
2	51	Запрос принят в обработку	Возникает в случае успешного приема запроса в обработку
3	52	Ответ не готов	Возникает в случае неготовности ответа по успешно принятому в обработку запросу	Используется при асинхронном запросе
4	53	Сведения в отношении юридического лица/индивидуального предпринимателя не могут быть предоставлены в электронном виде	Возникает при невозможности сформировать ответ на запрос электронном виде
5	82	Ошибка форматно-логического контроля	Возникает при условии несоответствия документа (запроса) xsd-схеме	Резерв, может не использоваться
6	83	Отсутствует запрос с указанным идентификатором запроса и видом запрошенных сведений от данного органа	Возникает в ситуации, когда в запросе на получение результата на запрос выписки по ЮЛ указан некорректный (неизвестный) идентификатор запроса и (или) запрос с таким идентификатором не поступал от данного органа	Используется при асинхронном запросе (при получении результата запроса выписки по ЮЛ)
9	99	Системная ошибка	Возникает при наличии внутренних ошибок в ПО ИС ФНС России

1. Контрольные примеры

Запрос на получение результата запроса на получение выписки по ЮЛ

Ответ на запрос на получение результата запроса на получение выписки по ЮЛ, в случае, запрос ещё не обработан

Ответ на запрос на получение результата запроса на получение выписки по ЮЛ с кодом возврата 53

Ответ на запрос на получение результата запроса на получение выписки по ЮЛ с ошибкой (код обработки которой не зарезервирован)
(меняются значения атрибутов и)

Примечание: условия возникновения данной ошибки в тестовой среде были инициированы искусственно. Данный пример описывает общую логику и структуру ответа с ошибкой. При проведении испытаний на продуктивной среде возврат точно такого же ответа без обеспечения необходимых условий не возможен.

1. Интерфейс должен принимать запросы по протоколу HTTPS с IP-адресов подсетей:
   • 79.142.16.0, маска 255.255.240.0 (20)
   • 91.232.230.0, маска 255.255.254.0 (23)
2. Интерфейс должен обрабатывать параметры, передаваемые системой методом HTTP GET.
3. Интерфейс должен формировать ответ системе в формате XML в кодировке UTF-8.
4. Обмен информацией ведется в режиме “запрос-ответ”, при этом скорость ответа не должна превышать 60 секунд, в противном случае система разрывает соединение по таймауту.
5. Если предполагаемое количество платежей за услуги подключаемого провайдера, ожидается интенсивным (до 10 платежей в минуту и более), необходимо, чтобы интерфейс поддерживал многопоточную коммуникацию до 10-15 одновременных соединений.
6. Интерфейс должен принимать запросы по протоколу HTTPS на один из следующих TCP-портов: 80, 81, 443, 8008, 8080, 8081, 8090, 8443, 4433. Использование иных портов не допускается.

Основные принципы работы интерфейса

Все запросы передаются методом GET, параметры передаются в пути запроса.

Передача информации о платеже провайдеру производится системой QIWI Wallet в два этапа – проверка статуса абонента и непосредственно проведение платежа. Также может добавляться предварительный этап получения дополнительных параметров платежа от провайдера, предоставляющего абоненту несколько сервисов, для информирования плательщика и добавления параметров платежа по выбору плательщика.

Тип запроса передается системой QIWI Wallet в переменной command – строка, принимающая значения check , pay или getInfo:

Параметры запросов

Все параметры обязательны в тех запросах, в которых они используются.

Параметр	Формат	Описание	В каких запросах используется
txn_id	Целое число длиной до 20 знаков	Уникальный идентификатор платежа в системе QIWI. По этому идентификатору производится и решение спорных вопросов.	check , pay
sum	Дробное число с точностью до сотых, в качестве разделителя используется. (точка). Если сумма представляет целое число, то оно все равно дополняется точкой и нулями, например – 152.00 .	Сумма платежа	check , pay
ccy	Код валюты Alpha-3 ISO 4217	Валюта платежа	check , pay
txn_date	ГГГГММДДЧЧММСС	Дата платежа (под датой платежа в системе подразумевается дата получения запроса от клиента). По этой дате производится дальнейшая сверка взаиморасчётов между QIWI Wallet и провайдером. Например, клиент отправил запрос в систему QIWI Wallet 31.12.2010 в 23:59:59, и система QIWI Wallet отправила свой запрос провайдеру 01.01.2011 в 00:00:05. Это может привести к проблеме сверки платежей, если система провайдера поместит транзакцию в следующий расчётный период. Чтобы избежать подобных проблем, QIWI Wallet предоставляет провайдеру оригинальную дату платежа.	pay
account	Строка, содержащая буквы, цифры и спецсимволы, длиной до 200 символов	Идентификатор абонента. Провайдер идентифицирует своего абонента по уникальному идентификатору (номер лицевого счета, телефона, логин и т.д.). Перед отправкой провайдеру, идентификатор проходит проверку корректности в соответствии с регулярным выражением, которое .	check , pay , getInfo
extra	Допустимыми являются цифры (0-9), подчёркивание (_) и строчные буквы латинского алфавита (a-z)	Дополнительные реквизиты платежа (экстра поля). Данные параметры могут быть использованы в случае, если платёж невозможно провести без дополнительных данных (одного идентификатора пользователя в системе провайдера недостаточно). Например, идентификатор пользователя – номер кредитной карты, но для проведения платежа также нужно указать срок действия карты. Перечень необходимых полей для передачи провайдеру необходимо указывать в .	check , pay
prvId	Целое число	Идентификатор сервиса в общей системе провайдера.	getInfo
parameter_name	Формат имени и значения параметров указывается провайдером в .	Дополнительные параметры для идентификации абонента	getInfo

Для поддержки расширяемости и сохранения работоспособности сервиса провайдера в период включения различных функций, предусмотренных протоколом (например, включение передачи новых реквизитов платежа), предполагается, что провайдер не препятствует появлению в запросе новых HTTP-параметров.

Гарантируется, что появление новых параметров в запросе не приведет к необходимости изменения обработки запросов со стороны провайдера, за исключением случаев, когда такое изменение логики было согласовано с провайдером.

Формат ответа

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

123323498 12369Bdkjh9 100.00 643 2012-04-05T12:00:07 0

В случае если любой из запросов провайдеру завершается ошибкой, то провайдер возвращает код ошибки в соответствии с .

В информационной системе провайдера не должно содержаться двух успешно проведенных платежей с одним и тем же номером txn_id . Если система повторно присылает запрос с уже существующим в информационной системе провайдера идентификатором txn_id , то провайдер должен вернуть результат обработки предыдущего запроса.

В ответе могут присутствовать следующие теги:

Например, имеет место ситуация: клиент прислал в систему запрос 31.12.2010 в 23:59:59. Учитывая задержку на обработку данных и пересылку информации по каналам связи, провайдером платеж будет получен 1.01.2011 00:00:05 и, соответственно, учтен в системе провайдера в другом отчетном периоде. Чтобы при проведении сверок проблем с разными отчетными периодами не возникало, необходимо, чтобы провайдер возвращал дату, по которой производится учет в его системе.

Пример запроса на проверку состояния счета абонента и регистрацию платежа

Условия примера:

Платежное приложение провайдера payment_app располагается по адресу yourservice.prv.ru , сервер поддерживает HTTPS соединения по порту 8443.

Для проверки состояния абонента система QIWI Wallet генерирует запрос (см. вкладку справа).

GET /payment_app?command=check&txn_id=1234567& account=4957835959&sum=10.45&ccy=RUB 1234567 2016AB 10.45 RUB 0 OK

Запрос содержит параметры:

• command=check – идентификатор запроса на проверку состояния абонента;

Успешный ответ провайдера (см. вкладку справа).

Возвращение result=0 на запрос check свидетельствует о том, что лицевой счет абонента с соответствующим ему номером в поле account может быть пополнен на сумму, указанную в запросе в поле sum . После успешной проверки состояния счета абонента система переходит к формированию и отправке запроса на пополнение баланса (запрос pay).

Пример запроса на пополнение лицевого счета

Условия примера:

Для подтверждения платежа система QIWI Wallet генерирует запрос (см. вкладку справа).

GET /payment_app?command=pay&txn_id=1234567& txn_date=20110815120133&account=4957835959&sum=10.45&ccy=RUB HTTP / 1.1 Host : yourservice.prv.ru:8443 Ответ провайдера 1234567 2016AB 10.45 RUB 0 OK 2011-08-15T12:06:45

Запрос содержит параметры:

• command=pay – идентификатор запроса на пополнение баланса абонента;
• txn_id=1234567 – внутренний номер платежа в системе QIWI;
• txn_date=20090815120133 – дата учета платежа в системе QIWI;
• account=4957835959 – идентификатор абонента в информационной системе провайдера;
• sum=10.45 – сумма к зачислению на лицевой счет абонента;
• ccy=RUB – валюта суммы зачисления на лицевой счет абонента.

Возвращая result=0 на запрос pay , провайдер сообщает об успешном завершении операции пополнения баланса. Система полностью завершает обработку данной транзакции.

В необязательном поле comment содержится служебный комментарий.

Пример запроса на получение дополнительных данных платежа

Условия примера:

Платежное приложение провайдера payment_app располагается по адресу yourservice.prv.ru , сервер поддерживает HTTPS соединения на порт 8443.

Для получения дополнительных данных платежа система QIWI Wallet генерирует запрос (см. вкладку справа).

GET /payment_app?command=getInfo&prvId=12345& account=4957835959&name1=%26%30AB&name2=0 HTTP / 1.1 Host : yourservice.prv.ru:8443 Ответ провайдера account1 term2 0 OK

Запрос содержит параметры:

• command=getInfo – идентификатор запрос на получение дополнительных данных платежа для абонента;
• prvId=12345 – идентификатор для определения сервиса провайдера;
• account=4957835959 – идентификатор абонента в информационной системе провайдера;
• name1 , name2 – дополнительные идентификаторы абонента.

Ответ провайдера см. на вкладке справа.

Возвращение result=0 на запрос getInfo свидетельствует о том, что запрос выполнен успешно и дополнительные данные для отображения абоненту получены.

В необязательном поле comment содержится служебный комментарий.

Ежедневная сверка

До 10:00 по московскому времени система генерирует и отправляет по указанному адресу электронный реестр принятых платежей за предыдущий день.

Реестр имеет следующую структуру:

Transaction date (Moscow);Report date;Type;Transaction number;Transaction currency ID;Transaction amount;Merchant"s comment;Merchant"s transaction/invoice number;Invoice date of issue;QW ID;Account;Refund ID

;;Payment;;;;;;;;;

;;Payment;;;;;;;;;

Поля разделены знаком; , дробная часть суммы отделена точкой, дата/время – Московские, перевод строки может состоять как из символов x0D x0A, так и просто из x0D.

Например:

31.02.2005 00:04:00;31.02.2005

00:00:00;Payment;3464968222;USD;5.00;;;;;0957835959;;

31.02.2005 00:04:00;31.02.2005 00:00:00;Payment;3464968912;RUB;10.34;;;;;[email protected];;

31.02.2005 00:11:00;31.02.2005 00:00:00;Payment;3464974548;EUR;4.72;;;;;ABC-12345;;

Система включает в реестр только успешно проведенные платежи.

Подтвержденными считаются платежи, которые пришли как при online обмене сообщениями, так и в реестре.

Если в реестре отсутствуют платежи, которые проведены в базе провайдера, или содержатся платежи, которых нет в базе провайдера, или при неполучении реестра необходимо связаться с контактным лицом QIWI, указанным в договоре, до 12:00 для выяснения ситуации и принятия решения.

Дополнительные возможности авторизации запросов

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

Эти авторизационные данные передаются по стандартным правилам basic-аутентификации при запросах по HTTP(S). К запросу добавляется HTTP-заголовок Authorization . В заголовке указывается строка Basic (с пробелом на конце) и пара “логин:пароль”, закодированная в BASE64:

Authorization: Basic ***

BASE64("Login:Password") = "***"

Заявка на подключение (образец)

Список кодов завершения

При обработке запросов от системы, провайдер должен сопоставить все возникающие в его приложении ошибки с приведенным ниже списком и возвращать соответствующие коды в элементе.

Знак + в столбце “фатальность” указывает на признак фатальности ошибки. Для системы QIWI Wallet фатальная ошибка означает, что повторная отправка запроса с теми же параметрами приведет к 100% повторению той же ошибки – следовательно, система прекращает обработку клиентского запроса и завершает его с ошибкой.

Нефатальная ошибка означает для системы, что повторение запроса с теми же параметрами через некоторый промежуток времени, возможно, приведет к успеху. Система будет повторять запросы, завершающиеся нефатальной ошибкой, постоянно увеличивая интервал, пока операция не завершится успехом или фатальной ошибкой, либо пока не истечет срок жизни запроса – 24 часа.

Отсутствие связи с сервером провайдера является нефатальной ошибкой.

Отсутствие в ответе элемента (некорректный XML, страница Service temporarily unavailable и т.д.) также является нефатальной ошибкой.

Код