Протокол взаимодействия с провайдерами QIWI
API предназначен для приёма платежей через интерфейсы QIWI Кошелька. Подробности см. в разделе «Руководства по интеграции» → «Приём платежей» → «Приём платежей наличными».
Используемые в тексте термины описаны в разделе «Руководства по интеграции» → «Термины и бизнес-сущности».
Взаимодействие информационных систем QIWI и провайдера строится в режиме "запрос-ответ", где инициатором запроса всегда является QIWI, а отвечающей стороной — провайдер.
Требования к интерфейсу провайдера
- Интерфейс должен принимать запросы по протоколу HTTPS на один из следующих TCP-портов:
80,81,443,8008,8080,8081,8090,8443,4433. Использование иных портов не допускается. - Интерфейс должен обрабатывать запросы, передаваемые методами
HTTP GET,HTTP POST. МетодомGETпараметры передаются в пути запроса, методомPOST— в теле запроса в виде URLencoded-строки. - Интерфейс должен формировать ответ на запрос в формате XML в кодировке UTF-8.
- Скорость ответа не должна превышать 60 секунд, в ином случае сервер QIWI разрывает соединение по таймауту.
- Если количество платежей за услуги провайдера ожидается интенсивным (до 10 платежей в минуту и более), интерфейс должен поддерживать многопоточную коммуникацию до 10-15 соединений одновременно.
-
Используйте сертификаты для безопасной работы с сервисами QIWI.
SSL-сертификат (SSL – Secure Socket Layer) *.qiwi.com предназначен для шифрования трафика между партнером и сервисами QIWI, чтобы не передавать персональные и платёжные данные по сети в открытом виде.
У SSL-сертификата есть срок действия, поэтому процедура его замены должна быть регулярной. QIWI обновляет сертификат ежегодно.
Скачайте по ссылке https://static.qiwi.com/ru/files/ssl_certificate_QIWI.zip актуальный публичный сертификат для использования клиентским программным обеспечением.
- Интерфейс должен принимать запросы только с IP-адресов подсетей QIWI:
- 79.142.16.0/20
- 195.189.100.0/22
- 91.232.230.0/23
- 91.213.51.0/24
Авторизация запросов
Для авторизации провайдер предоставил пару Login:Password.
Пара кодируется в Base64:
BASE64("Login:Password") = "***"
В HTTP-запросе от QIWI передаётся заголовок
Authorization: Basic ***
По умолчанию запросы от QIWI поступают без авторизационных данных. Чтобы добавить авторизационные данные в запросы, предоставьте при подключении идентификатор (логин) и секретный пароль.
Сервер QIWI будет передавать логин и пароль по стандартным правилам basic-аутентификации:
- К запросу добавляется HTTP-заголовок
Authorization. - В заголовке указывается строка
Basic(с пробелом на конце) и паралогин:пароль, закодированная в Base64.
Также поддерживается авторизация запросов по клиентскому SSL-сертификату. Для использования такой авторизации предоставьте клиентский сертификат в формате PKCS12 при подключении.
Проверка статуса абонента в информационной системе провайдера
При получении запроса провайдер:
- проверяет наличие в своей базе абонента с указанным идентификатором;
- выполняет внутренние проверки идентификатора и суммы платежа в соответствии с принятой логикой пополнения лицевых счетов через платежные системы.
Параметры запроса
Запрос проверки статуса абонента
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 — текст для печати на чеке при совершении платежа (используется только для платежей с QIWI Терминалов) |
| 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=20220815120133&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&txn_date=20220815120133&account=4950001111&sum=10.45&pay_type=1&account1=test1&data1=osmp
| Параметр | Описание |
|---|---|
| command | Обязательный параметр. Идентификатор типа запроса: пополнить баланс абонента. Всегда равен pay |
| txn_id | Обязательный параметр. Идентификатор платежа в информационной системе QIWI. В информационной системе провайдера не должно содержаться двух успешно проведенных платежей с одним и тем же идентификатором платежа. При получении запроса с txn_id, уже существующим в информационной системе провайдера, провайдер должен вернуть результат обработки предыдущего запроса. |
| txn_date | Обязательный параметр. Дата операции в формате YYYYMMDDHHMMSS |
| 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 – текст для печати на чеке при совершении платежа (используется только для платежей с QIWI Терминалов) |
| fields.field1.name, …, fields.fieldN.name | Имя параметра. Если не указано, присваивается имя disp1,..,dispN (в соответствии с порядковым номером тега fieldN) |
| pay_id | Информация о шлюзе провайдера, в котором будет зафиксирован платеж. Информация о том, какие шлюзы доступны для выбора, уточняется при тестировании взаимодействия с информационной системой QIWI. |
Формат стандартного реестра платежей
Информационная система QIWI включает в реестр только успешно проведенные платежи.
Реестр — это текстовый файл следующего формата:
-
Первая строка содержит заголовок:
<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
Коды ошибок
Коды ошибок могут быть фатальные и нефатальные:
-
Фатальная ошибка означает, что повторная отправка запроса с теми же параметрами приведет к 100% повторению той же ошибки. В этом случае информационная система QIWI прекращает обработку запроса и завершает его с ошибкой.
Пример фатальной ошибки — отсутствие в ответе тега
<result>. -
Нефатальная ошибка означает, что повторение запроса с теми же параметрами через некоторый промежуток времени, возможно, приведет к успеху. При получении нефатальной ошибки информационная система QIWI будет повторять запросы, увеличивая интервал, пока операция не завершится успехом или фатальной ошибкой, либо пока не истечет срок жизни платежа (24 часа).
Пример нефатальной ошибки — отсутствие связи с сервером провайдера.
| Код | Описание | Фатальность |
|---|---|---|
| 0 | ОК | Нет |
| 1 | Временная ошибка. Повторите запрос позже | Нет |
| 4 | Неверный формат идентификатора абонента | Да |
| 5 | Идентификатор абонента не найден (Ошиблись номером) | Да |
| 7 | Прием платежа запрещен провайдером | Да |
| 8 | Прием платежа запрещен по техническим причинам | Да |
| 79 | Счет абонента не активен | Да |
| 90 | Проведение платежа не окончено | Нет |
| 241 | Сумма слишком мала | Да |
| 242 | Сумма слишком велика | Да |
| 243 | Невозможно проверить состояние счета | Да |
| 300 | Другая ошибка провайдера | Нет |