Вопросы
bss@qiwi.com
NAV Navbar

Протокол взаимодействия с провайдерами QIWI

Взаимодействие информационных систем QIWI и провайдера строится в режиме "запрос-ответ", где инициатором запроса всегда является QIWI, а отвечающей стороной – провайдер.

Каждый платеж в QIWI имеет уникальный идентификатор, который передается в каждом запросе. По этому идентификатору производится сверка взаиморасчетов и решение спорных вопросов.

Чтобы подключить Протокол, провайдер должен:

Требования к интерфейсу провайдера

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

Процесс платежа

В процессе платежа информационная система QIWI последовательно выполняет следующие шаги:

Обработку запросов на каждом из этих шагов провайдеру необходимо реализовать на своей стороне.

Правила обработки запросов

При обработке запроса от информационной системы QIWI провайдер должен выполнить запрашиваемую операцию и передать в ответе данные (если это требуется) и код выполнения операции в формате XML-документа. Провайдер должен сопоставить все возникающие в его приложении ошибки со списком кодов ошибок и возвращать соответствующий код в теге <result> ответа.

Коды ошибок могут быть фатальные и нефатальные:

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

Признак того что ошибка фатальная (Фатальность) указан в списке кодов ошибок.

Проверка статуса абонента в информационной системе провайдера

При получении запроса провайдер:

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

Пример запроса

POST /payment_app.cgi HTTP/1.1
Accept: application/xml
Content-type: application/x-www-form-urlencoded; charset=utf-8
Host: example.com: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: example.com: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: example.com: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: example.com: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 по московскому времени система генерирует и отправляет по указанному адресу электронный реестр принятых платежей за предыдущий день.

Реестр является текстовым файлом и имеет следующую структуру:

Поля разделены знаком табуляции, дробная часть суммы отделена точкой, дата/время Московские, перевод строки может состоять из символов 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 даты получения реестра для выяснения ситуации и принятия решения, если:

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

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

Логин и пароль передаются по стандартным правилам basic-аутентификации при запросах по HTTPS:

Также поддерживается авторизация запросов по клиентскому SSL-сертификату. Для этого укажите необходимость такой авторизации в заявке на подключение.

Коды ошибок

Код Описание Фатальность
0 ОК Нет
1 Временная ошибка. Повторите запрос позже Нет
4 Неверный формат идентификатора абонента Да
5 Идентификатор абонента не найден (Ошиблись номером) Да
7 Прием платежа запрещен провайдером Да
8 Прием платежа запрещен по техническим причинам Да
79 Счет абонента не активен Да
90 Проведение платежа не окончено Нет
241 Сумма слишком мала Да
242 Сумма слишком велика Да
243 Невозможно проверить состояние счета Да
300 Другая ошибка провайдера Нет