Протокол взаимодействия с провайдерами QIWI
Взаимодействие информационных систем QIWI и провайдера строится в режиме "запрос-ответ", где инициатором запроса всегда является QIWI, а отвечающей стороной – провайдер.
Каждый платеж в QIWI имеет уникальный идентификатор, который передается в каждом запросе. По этому идентификатору производится сверка взаиморасчетов и решение спорных вопросов.
Чтобы подключить Протокол, провайдер должен:
- выполнить требования к интерфейсу провайдера;
- реализовать процесс платежа;
- соблюдать правила обработки запросов.
Требования к интерфейсу провайдера
- Интерфейс должен принимать запросы по протоколу HTTPS с IP-адресов подсетей:
79.142.16.0/2091.232.230.0/23
- Интерфейс должен обрабатывать параметры, передаваемые методами
HTTP GET,HTTP POST. МетодомGETпараметры передаются в пути запроса, методомPOST- в теле запроса в виде URLencoded-строки. - Интерфейс должен формировать ответ в формате XML в кодировке UTF-8.
- Скорость ответа не должна превышать 60 секунд, в противном случае Система разрывает соединение по таймауту.
- Если предполагаемое количество платежей за услуги подключаемого провайдера, ожидается интенсивным (до 10 платежей в минуту и более), необходимо, чтобы интерфейс поддерживал многопоточную коммуникацию до 10-15 одновременных соединений.
- Интерфейс должен принимать запросы по протоколу HTTPS на один из следующих TCP-портов:
80,81,443,8008,8080,8081,8090,8443,4433. Использование иных портов не допускается.
Процесс платежа
В процессе платежа информационная система QIWI последовательно выполняет следующие шаги:
Обработку запросов на каждом из этих шагов провайдеру необходимо реализовать на своей стороне.
Правила обработки запросов
При обработке запроса от информационной системы QIWI провайдер должен выполнить запрашиваемую операцию и передать в ответе данные (если это требуется) и код выполнения операции в формате XML-документа. Провайдер должен сопоставить все возникающие в его приложении ошибки со списком кодов ошибок и возвращать соответствующий код в теге <result> ответа.
Коды ошибок могут быть фатальные и нефатальные:
- Фатальная ошибка означает, что повторная отправка запроса с теми же параметрами приведет к 100% повторению той же ошибки. В этом случае информационная система QIWI прекращает обработку клиентского запроса и завершает его с ошибкой.
- Нефатальная ошибка означает, что повторение запроса с теми же параметрами через некоторый промежуток времени, возможно, приведет к успеху. При получении нефатальной ошибки информационная система QIWI будет повторять запросы, увеличивая интервал, пока операция не завершится успехом или фатальной ошибкой, либо пока не истечет срок жизни платежа (24 часа).
Например, отсутствие связи с сервером провайдера является нефатальной ошибкой. Отсутствие в ответе тега <result> является фатальной ошибкой.
Признак того что ошибка фатальная (Фатальность) указан в списке кодов ошибок.
Проверка статуса абонента в информационной системе провайдера
При получении запроса провайдер:
- проверяет наличие в своей базе абонента с указанным идентификатором;
- выполняет внутренние проверки идентификатора и суммы платежа в соответствии с принятой логикой пополнения лицевых счетов через платежные системы.
Параметры запроса
Пример запроса
POST /payment_app.cgi HTTP/1.1
Accept: application/xml
Content-type: application/x-www-form-urlencoded; charset=utf-8
Host: service.someprv.ru:8443
command=check&txn_id=1234567&account=4950001111&sum=10.45
Пример запроса с дополнительными параметрами
POST /payment_app.cgi HTTP/1.1
Accept: application/xml
Content-type: application/x-www-form-urlencoded; charset=utf-8
Host: service.someprv.ru:8443
command=check&txn_id=1234567&account=4950001111&sum=10.45&pay_type=1&account1=test1&data1=osmp
| Параметр | Условие | Описание |
|---|---|---|
| command | Обязательно | Идентификация типа запроса: проверить счет абонента. Всегда равен check |
| txn_id | Обязательно | Идентификатор платежа в информационной системе QIWI. В информационной системе провайдера не должно содержаться двух успешно проведенных платежей с одним и тем же идентификатором платежа. При получении запроса с txn_id, уже существующим в информационной системе провайдера, провайдер должен вернуть результат обработки предыдущего запроса. |
| account | Обязательно | Идентификатор абонента в информационной системе провайдера |
| sum | Обязательно | Сумма операции |
| pay_type | Опционально | Идентификатор услуги, предоставляемой провайдером (Используется, если провайдер предоставляет более 1 услуги) |
| prv_id | Опционально | Внутренний идентификатор провайдера в информационной системе QIWI (используется для консолидаторов) |
| data1,data2,…,dataN | Опционально | Дополнительные параметры, передаваемые провайдеру |
| account1, account2,…,accountN | Опционально | Номера дополнительных счетов абонента в информационной системе провайдера |
Параметры ответа
Пример ответа
<?xml version="1.0" encoding="UTF-8"?>
<response>
<osmp_txn_id>1234567</osmp_txn_id>
<result>0</result>
<comment>Some comment</comment>
</response>
Пример ответа с дополнительными параметрами
<?xml version=”1.0” encoding="UTF-8"?>
<response>
<osmp_txn_id>1234567</osmp_txn_id>
<result>0</result>
<fields>
<field1 name="name1" type="disp">value1</field1>
<field2 name="name2" type="disp">value2</field2>
<field3 name="name3" type="prt-data">value3</field3>
</fields>
</response>
В ответе интерфейс провайдера должен вернуть XML-документ, содержащий блок <response> со следующими тегами:
| Тег | Условие | Описание |
|---|---|---|
| osmp_txn_id | Обязательно | Идентификатор транзакции в информационной системе QIWI (txn_id из запроса) |
| result | Обязательно | Код результата операции. В случае, если платеж разрешен, возвращается 0. |
| comment | Опционально | Комментарий к операции |
| fields | Опционально | Тег с информацией об абоненте или об операции |
| fields.field1, …, fields.fieldN | Опционально | Параметры, содержащие информацию |
| fields.field1.type, …, fields.fieldN.type | Опционально | Тип параметра. Возможно использование следующих типов параметров:disp – информация для отображения клиенту при совершении платежа (по умолчанию, если тип не указан);info – информация для сохранения в информационной системе QIWI;prt-data — текст для печати на чеке при совершении платежа (используется только для платежей с АСО) |
| fields.field1.name, …, fields.fieldN.name | Опционально | Имя параметра. Если не указано, присваивается имя disp1,..,dispN (в соответствии с порядковым номером тега fieldN) |
| pay_id | Опционально | Информация о шлюзе провайдера, в котором будет зафиксирован платеж. Информация о том, какие шлюзы доступны для выбора, уточняется при тестировании взаимодействия с информационной системой QIWI. |
Регистрация платежа
При получении запроса провайдер пополняет баланс абонента на указанную сумму.
Параметры запроса
Пример запроса
POST /payment_app.cgi HTTP/1.1
Accept: application/xml
Content-type: application/x-www-form-urlencoded; charset=utf-8
Host: service.someprv.ru:8443
command=pay&txn_id=1234567&txn_date=account=4950001111&sum=10.45
Пример запроса с дополнительными параметрами
POST /payment_app.cgi HTTP/1.1
Accept: application/xml
Content-type: application/x-www-form-urlencoded; charset=utf-8
Host: service.someprv.ru:8443
command=pay&txn_id=1234567&account=4950001111&sum=10.45&pay_type=1&account1=test1&data1=osmp
| Параметр | Условие | Описание |
|---|---|---|
| command | Обязательно | Идентификация типа запроса: пополнить баланс абонента. Всегда равен pay |
| txn_id | Обязательно | Идентификатор платежа в информационной системе QIWI. В информационной системе провайдера не должно содержаться двух успешно проведенных платежей с одним и тем же идентификатором платежа. При получении запроса с txn_id, уже существующим в информационной системе провайдера, провайдер должен вернуть результат обработки предыдущего запроса. |
| txn_date | Обязательно | Дата операции |
| account | Обязательно | Идентификатор абонента в информационной системе провайдера |
| sum | Обязательно | Сумма операции |
| pay_type | Опционально | Идентификатор услуги, предоставляемой провайдером (Используется, если провайдер предоставляет более 1 услуги) |
| prv_id | Опционально | Внутренний идентификатор провайдера в информационной системе QIWI (используется для консолидаторов) |
| data1, data2,…, dataN | Опционально | Дополнительные параметры, передаваемые провайдеру |
| account1, account2,…, accountN | Опционально | Номера дополнительных счетов абонента в информационной системе провайдера |
Параметры ответа
Пример ответа
<?xml version="1.0" encoding="UTF-8"?>
<response>
<osmp_txn_id>1234567</osmp_txn_id>
<prv_txn>123</prv_txn>
<sum>10.00</sum>
<result>0</result>
</response>
Пример ответа с дополнительными параметрами
<?xml version=”1.0” encoding="UTF-8"?>
<response>
<osmp_txn_id>1234567</osmp_txn_id>
<prv_txn>2016</prv_txn>
<sum>1.00</sum>
<result>0</result>
<fields>
<field1 name="name1" type="disp">value1</field1>
<field2 name="name2" type="disp">value2</field2>
<field3 name="name3" type="prt-data">value3</field3>
</fields>
</response>
В ответе интерфейс провайдера должен вернуть XML-документ, содержащий блок <response> со следующими тегами:
| Тег | Условие | Описание |
|---|---|---|
| osmp_txn_id | Обязательно | Идентификатор транзакции в информационной системе QIWI (txn_id из запроса) |
| prv_txn | Обязательно | Уникальный номер операции пополнения баланса абонента (в информационной системе провайдера) |
| sum | Обязательно | Сумма платежа, переданная провайдеру |
| result | Обязательно | Код результата операции (result=0 в случае успешной регистрации платежа) |
| comment | Опционально | Комментарий к операции |
| fields | Опционально | Тег с информацией об абоненте или об операции |
| fields.field1, …, fields.fieldN | Опционально | Параметры, содержащие информацию |
| fields.field1.type, …, fields.fieldN.type | Опционально | Тип параметра. Возможно использование следующих типов параметров:disp – информация для отображения клиенту при совершении платежа (по умолчанию, если тип не указан);info – информация для сохранения в информационной системе QIWI;prt-data – текст для печати на чеке при совершении платежа (используется только для платежей с АСО) |
| fields.field1.name, …, fields.fieldN.name | Опционально | Имя параметра. Если не указано, присваивается имя disp1,..,dispN (в соответствии с порядковым номером тега fieldN) |
| pay_id | Опционально | Информация о шлюзе провайдера, в котором будет зафиксирован платеж. Информация о том, какие шлюзы доступны для выбора, уточняется при тестировании взаимодействия с информационной системой QIWI. |
Ежедневная сверка
До 10:00 по московскому времени система генерирует и отправляет по указанному адресу электронный реестр принятых платежей за предыдущий день.
Реестр является текстовым файлом и имеет следующую структуру:
-
Первая строка содержит заголовок:
<email адрес, на который будет послана сверка> -
Вторая и последующие строки содержат информацию о платежах:
<txn_id> <дата> <время> <идентификатор абонента> <сумма> -
Последняя строка содержит общее количество и сумму платежей в реестре:
Total: <число платежей> <сумма платежей>
Поля разделены знаком табуляции, дробная часть суммы отделена точкой, дата/время Московские, перевод строки может состоять из символов x0D x0A, или только из x0D. Например:
test@osmp.ru
12345678 20.08.2021 12:13:14 0957000059 123.45
12345678 20.08.2021 13:22:34 8002000059 0.01
12345678 20.08.2021 14:55:11 9161234567 123.01
12345689 20.08.2021 14:55:12 0732123456 1000.00
Total: 4 1246.47
Информационная система QIWI включает в реестр только успешно проведенные платежи.
Подтвержденными считаются платежи, которые поступили и при онлайн-обмене сообщениями, и в реестре.
Необходимо связаться с контактным лицом КИВИ, указанным в договоре, до 12:00 даты получения реестра для выяснения ситуации и принятия решения, если:
- в реестре отсутствуют платежи, которые проведены в информационной системе провайдера;
- в реестре содержатся платежи, которых нет в информационной системе провайдера;
- реестр не получен в указанное время (до 10:00).
Дополнительные возможности авторизации запросов
В заявке на подключение провайдер может задать идентификатор (логин) и секретный пароль к нему, используемые для авторизации запросов от QIWI.
Логин и пароль передаются по стандартным правилам basic-аутентификации при запросах по HTTPS:
- К запросу добавляется HTTP-заголовок
Authorization. -
В заголовке указывается строка
Basic(с пробелом на конце) и пара "логин:пароль", закодированная в BASE64:Authorization: Basic ***Здесь:
BASE64("Login:Password") = "***"
Также поддерживается авторизация запросов по клиентскому SSL-сертификату. Для этого укажите необходимость такой авторизации в заявке на подключение.
Коды ошибок
| Код | Описание | Фатальность |
|---|---|---|
| 0 | ОК | Нет |
| 1 | Временная ошибка. Повторите запрос позже | Нет |
| 4 | Неверный формат идентификатора абонента | Да |
| 5 | Идентификатор абонента не найден (Ошиблись номером) | Да |
| 7 | Прием платежа запрещен провайдером | Да |
| 8 | Прием платежа запрещен по техническим причинам | Да |
| 79 | Счет абонента не активен | Да |
| 90 | Проведение платежа не окончено | Нет |
| 241 | Сумма слишком мала | Да |
| 242 | Сумма слишком велика | Да |
| 243 | Невозможно проверить состояние счета | Да |
| 300 | Другая ошибка провайдера | Нет |