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

Общие принципы протокола

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

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

При обработке запроса от Системы провайдер должен выполнить требуемую операцию, а затем передать в ответе Системе данные (если это требуется) и результат выполнения операции.

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

  1. Интерфейс должен принимать запросы по протоколу HTTPS с IP-адресов подсетей:
    • 79.142.16.0, маска 255.255.240.0 (20)
    • 91.232.230.0, маска 255.255.254.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. Использование иных портов не допускается.

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

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

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

Описание операций

Запрос check

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

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

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

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 Обязательно Идентификатор платежа в Системе. В базе провайдера не должно содержаться двух успешно проведенных платежей с одним и тем же идентификатором платежа. При получении запроса со значением txn_id, уже существующим в базе провайдера, провайдер должен вернуть результат обработки предыдущего запроса.
account Обязательно Идентификатор абонента в информационной системе провайдера
sum Обязательно Сумма операции
pay_type Опционально Идентификатор услуги, предоставляемой провайдером (Используется, если провайдер предоставляет более 1 услуги)
prv_id Опционально Внутренний идентификатор провайдера в Системе КИВИ (используется для консолидаторов)
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 Обязательно Идентификатор транзакции в Системе (txn_id из запроса)
result Обязательно Код результата операции (result=0 в случае возможности принятия платежа)
comment Опционально Комментарий к операции
fields Опционально Тег с информацией об абоненте или об операции
fields.field1, …, fields.fieldN Опционально Параметры, содержащие информацию
fields.field1.type, …, fields.fieldN.type Опционально Тип параметра. Возможно использование следующих типов параметров:
disp – информация для отображения клиенту при совершении платежа (по умолчанию, если тип не указан);
info – информация для сохранения в Системе;
prt-data – текст для печати на чеке при совершении платежа (используется только для платежей с АСО)
fields.field1.name, …, fields.fieldN.name Опционально Имя параметра. Если не указано, присваивается имя disp1,..,dispN (в соответствии с порядковым номером тега fieldN)
pay_id Опционально Информация о шлюзе провайдера, в котором будет зафиксирован платеж. Информация о том, какие шлюзы доступны для выбора, уточняется при тестировании в Системе.

Запрос pay

При получении запроса pay провайдер должен произвести пополнение баланса абонента.

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

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

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

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

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 Обязательно Идентификатор платежа в Системе. В базе провайдера не должно содержаться двух успешно проведенных платежей с одним и тем же идентификатором платежа. При получении запроса со значением txn_id, уже существующим в базе провайдера, провайдер должен вернуть результат обработки предыдущего запроса.
txn_date Обязательно Дата операции
account Обязательно Идентификатор абонента в информационной системе провайдера
sum Обязательно Сумма операции
pay_type Опционально Идентификатор услуги, предоставляемой провайдером (Используется, если провайдер предоставляет более 1 услуги)
prv_id Опционально Внутренний идентификатор провайдера в Системе КИВИ (используется для консолидаторов)
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 Обязательно Идентификатор транзакции в Системе (txn_id из запроса)
prv_txn Обязательно Уникальный номер операции пополнения баланса абонента (в информационной системе провайдера)
sum Обязательно Сумма платежа, переданная провайдеру
result Обязательно Код результата операции (result=0 в случае успешной регистрации платежа)
comment Опционально Комментарий к операции
fields Опционально Тег с информацией об абоненте или об операции
fields.field1, …, fields.fieldN Опционально Параметры, содержащие информацию
fields.field1.type, …, fields.fieldN.type Опционально Тип параметра. Возможно использование следующих типов параметров:
disp – информация для отображения клиенту при совершении платежа (по умолчанию, если тип не указан);
info – информация для сохранения в Системе;
prt-data – текст для печати на чеке при совершении платежа (используется только для платежей с АСО)
fields.field1.name, …, fields.fieldN.name Опционально Имя параметра. Если не указано, присваивается имя disp1,..,dispN (в соответствии с порядковым номером тега fieldN)
pay_id Опционально Информация о шлюзе провайдера, в котором будет зафиксирован платеж. Информация о том, какие шлюзы доступны для выбора, уточняется при тестировании в Системе.

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

До 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

<datetime>;<prv_date>;Payment;<txn_id>;<ccy>;<amount>;<empty>;<empty>;<empty>;<empty>;<account>;<empty>

...

<datetime>;<prv_date>;Payment;<txn_id>;<ccy>;<amount>;<empty>;<empty>;<empty>;<empty>;<account>;<empty>

Поля разделены знаком ;, дробная часть суммы отделена точкой, дата/время – Московские, перевод строки может состоять как из символов 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;;;;;test@example.org;;

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

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

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

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

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

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

Authorization: Basic ***

Здесь:

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

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

Результаты выполнения запросов

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

В списке отдельно отмечены фатальные и нефатальные ошибки:

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

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