Интерфейс подключения провайдеров услуг к платежному сервису QIWI Wallet
API предназначен для приёма платежей через сеть QIWI Терминалов. Подробности см. в разделе «Руководства по интеграции» → «Приём платежей» → «Приём платежей наличными».
Используемые в тексте термины описаны в разделе «Руководства по интеграции» → «Термины и бизнес-сущности».
Взаимодействие сервиса QIWI Wallet и провайдера строится в режиме "запрос-ответ", где инициатором запроса всегда является QIWI Wallet, а отвечающей стороной – провайдер.
Требования к интерфейсу провайдера
- Интерфейс должен принимать запросы по протоколу 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=getInfo&prvId=12345&account=4957835959&name1=%26%30AB&name2=0
| Параметр | Формат | Описание |
|---|---|---|
| command | getInfo |
Обязательный параметр. Идентификатор типа запроса: запрос на получение дополнительных данных платежа для абонента. Всегда равен getInfo |
| account | Строка, содержащая буквы, цифры и спецсимволы, длиной до 200 символов | Обязательный параметр. Уникальный идентификатор абонента в информационной системе провайдера (номер лицевого счета, телефона, логин и т.д.). Перед отправкой провайдеру, идентификатор проходит проверку корректности в соответствии с регулярным выражением, которое предоставляет провайдер при подключении |
| prvId | Целое число | Обязательный параметр. Идентификатор сервиса в общей системе провайдера |
| parameter_name | Формат имени и значения параметров указывается провайдером | Дополнительные параметры для идентификации абонента |
Параметры ответа
Ответ на запрос получения дополнительных параметров платежа
<?xml version="1.0" encoding="UTF-8"?>
<response>
<type hasList="true" hasInfo="true"/>
<extra>
<list>
<field name="service1">account1</field>
</list>
<info>
<field name="service2">term2</field>
</info>
</extra>
<result>0</result>
<comment>OK</comment>
</response>
В ответе интерфейс провайдера должен вернуть XML-документ с блоком <response> и следующими тегами:
| Тег | Описание |
|---|---|
| type | Обязательный параметр. Признак присутствия/отсутствия секций <info> и <list> в ответе. Тег должен содержать обязательные атрибуты hasList и hasInfo. При этом, если атрибут hasList="true", обязательно наличие секции <list> внутри тега <extra> (см. далее). Аналогично, если атрибут hasInfo="true", обязательно наличие секции <info> внутри тега <extra> (см. далее) |
| extra | Список данных для клиента. Содержит вложенные теги |
| list | Обязательный параметр, если атрибут hasList="true". Список полей для выбора клиентом |
| field name="field1" | Каждый тег представляет поле из списка для выбора клиентом. Название поля указывается в атрибуте name, значение поля - в значении тега. В ответе может присутствовать несколько тегов с разными значениями атрибута. Выбранная пара в формате "extra[field1]=value" может передаваться провайдеру в запросах check и pay. |
| info | Обязательный параметр, если атрибут hasInfo="true". Список полей для отображения информации клиенту |
| field name="field1" | Каждый тег представляет поле из списка для отображения клиенту. Отображается значение тега. В ответе может присутствовать несколько тегов с разными значениями атрибутов. |
| result | Обязательный параметр. Код ошибки (<result>0</result> в случае успешной обработки запроса) |
| comment | Комментарий к операции |
Проверка статуса абонента в информационной системе провайдера
При получении запроса провайдер:
- проверяет наличие в своей базе абонента с указанным идентификатором;
- выполняет внутренние проверки идентификатора и суммы платежа в соответствии с принятой логикой пополнения лицевых счетов через платежные системы.
Параметры запроса
Запрос проверки статуса абонента
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=100.45&ccy=RUB
Запрос проверки статуса абонента с дополнительными параметрами
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=100.45&ccy=RUB&extra[name1]=data1
| Параметр | Формат | Описание |
|---|---|---|
| command | check |
Обязательный параметр. Идентификатор типа запроса: осуществить проверку счета абонента. Всегда равен check |
| txn_id | Целое число длиной до 20 знаков | Обязательный параметр. Идентификатор платежа в сервисе QIWI Wallet. В базе провайдера не должно содержаться двух успешно проведенных платежей с одним и тем же идентификатором платежа QIWI Wallet. При получении запроса со значением txn_id, уже существующим в базе провайдера, провайдер должен вернуть результат обработки предыдущего запроса. |
| account | Строка, содержащая буквы, цифры и спецсимволы, длиной до 200 символов | Обязательный параметр. Уникальный идентификатор абонента в информационной системе провайдера (номер лицевого счета, телефона, логин и т.д.). Перед отправкой провайдеру, идентификатор проходит проверку корректности в соответствии с регулярным выражением, которое предоставляет провайдер при подключении |
| sum | Дробное число с точностью до сотых, разделитель . (точка). Если сумма представляет целое число, то оно все равно дополняется точкой и нулями, например – 152.00. |
Обязательный параметр. Сумма к зачислению на лицевой счет абонента |
| ccy | Код валюты Alpha-3 ISO 4217 | Обязательный параметр. Валюта суммы операции |
| extra[parameter_name] | Цифры (0-9), подчёркивание (_) и строчные буквы латинского алфавита (a-z) |
Дополнительные реквизиты платежа (экстра-поля). Данные параметры могут быть использованы в случае, если платёж невозможно провести без дополнительных данных (одного идентификатора пользователя в системе провайдера недостаточно). Например, идентификатор пользователя – номер кредитной карты, но для проведения платежа также нужно указать срок действия карты. Перечень необходимых полей для передачи провайдеру необходимо указать при подключении. |
Параметры ответа
Ответ на запрос проверки статуса абонента
<?xml version="1.0" encoding="UTF-8"?>
<response>
<osmp_txn_id>1234567</osmp_txn_id>
<prv_txn>2016AB</prv_txn>
<sum>100.45</sum>
<ccy>RUB</ccy>
<result>0</result>
<comment>OK</comment>
</response>
В ответе интерфейс провайдера должен вернуть XML-документ с блоком <response> и следующими тегами:
| Тег | Описание |
|---|---|
| osmp_txn_id | Обязательный параметр. Идентификатор транзакции в QIWI Wallet (txn_id из запроса) |
| prv_txn | Обязательный параметр. Уникальный номер операции пополнения баланса абонент в системе провайдера |
| sum | Обязательный параметр. Параметр sum из запроса |
| ccy | Обязательный параметр. Параметр ccy из запроса |
| result | Обязательный параметр. Код ошибки (<result>0</result> в случае возможности принятия платежа) |
| comment | Комментарий к операции |
Регистрация платежа
При получении запроса провайдер пополняет баланс абонента на указанную сумму.
Параметры запроса
Запрос регистрации платежа
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=20110815120133&account=4957835959&sum=100.45&ccy=RUB
| Параметр | Формат | Описание |
|---|---|---|
| command | pay |
Обязательный параметр. Идентификатор типа запроса: осуществить пополнение баланса абонента. Всегда равен pay |
| txn_id | Целое число длиной до 20 знаков | Обязательный параметр. Идентификатор платежа в сервисе QIWI Wallet. В базе провайдера не должно содержаться двух успешно проведенных платежей с одним и тем же идентификатором платежа. При получении запроса со значением txn_id, уже существующим в базе провайдера, провайдер должен вернуть результат обработки предыдущего запроса. |
| txn_date | ГГГГММДДЧЧММСС |
Обязательный параметр. Дата платежа (под датой платежа в сервисе QIWI Wallet подразумевается дата получения запроса от клиента). По этой дате производится дальнейшая сверка взаиморасчётов между QIWI Wallet и провайдером. Например, клиент отправил запрос в систему QIWI Wallet 31.12.2019 в 23:59:59, и сервис QIWI Wallet отправил свой запрос провайдеру 01.01.2020 в 00:00:05. Это может привести к расхождению при сверке платежей, если система провайдера поместит транзакцию в следующий расчётный период. Чтобы избежать подобных проблем, QIWI Wallet предоставляет провайдеру оригинальную дату платежа. |
| account | Строка, содержащая буквы, цифры и спецсимволы, длиной до 200 символов | Обязательный параметр. Уникальный идентификатор абонента в информационной системе провайдера (номер лицевого счета, телефона, логин и т.д.). Перед отправкой провайдеру, идентификатор проходит проверку корректности в соответствии с регулярным выражением, которое предоставляет провайдер при подключении |
| sum | Дробное число с точностью до сотых, разделитель . (точка). Если сумма представляет целое число, то оно все равно дополняется точкой и нулями, например – 152.00. |
Обязательный параметр. Сумма к зачислению на лицевой счет абонента |
| ccy | Код валюты Alpha-3 ISO 4217 | Обязательный параметр. Валюта суммы операции |
| extra[parameter_name] | Цифры (0-9), подчёркивание (_) и строчные буквы латинского алфавита (a-z) |
Дополнительные реквизиты платежа (экстра поля). Данные параметры могут быть использованы в случае, если платёж невозможно провести без дополнительных данных (одного идентификатора пользователя в системе провайдера недостаточно). Например, идентификатор пользователя – номер кредитной карты, но для проведения платежа также нужно указать срок действия карты. Перечень необходимых полей для передачи провайдеру необходимо указать при подключении |
Параметры ответа
Ответ на запрос регистрации платежа
<?xml version="1.0" encoding="UTF-8"?>
<response>
<osmp_txn_id>1234567</osmp_txn_id>
<prv_txn>2016AB</prv_txn>
<sum>100.45</sum>
<ccy>RUB</ccy>
<result>0</result>
<comment>OK</comment>
<fields>
<field name="prv-date">2011-08-15T12:06:45</field>
</fields>
</response>
В ответе интерфейс провайдера должен вернуть XML-документ с блоком <response> и следующими тегами:
| Тег | Описание |
|---|---|
| osmp_txn_id | Обязательный параметр. Идентификатор транзакции в QIWI Wallet (txn_id из запроса) |
| prv_txn | Обязательный параметр. Уникальный номер операции пополнения баланса абонент в системе провайдера |
| sum | Обязательный параметр. Параметр sum из запроса |
| ccy | Обязательный параметр. Параметр ccy из запроса |
| result | Обязательный параметр. Код ошибки (<result>0</result> в случае возможности принятия платежа) |
| field name="prv-date" | Обязательный параметр. Дата и время принятия платежа в системе провайдера в формате ГГГГ-ММ-ДДTЧЧ:ММ:СС (например, 2011-02-03T00:00:07). Эта дата используется для бухгалтерских взаиморасчетов. |
| comment | Комментарий к операции |
Формат стандартного реестра платежей
Сервис QIWI Wallet включает в реестр только успешно проведенные платежи.
Реестр — это текстовый файл следующего формата:
-
Первая строка содержит заголовок с названиями полей:
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 -
Вторая и последующие строки содержат данные:
<txn_date>;<prv-date>;Payment;<txn_id>;<ccy>;<amount>;<empty>;<empty>;<empty>;<empty>;<account>;<empty>
Поля разделены знаком ;, дробная часть суммы отделена точкой, дата/время – Московские, перевод строки может состоять как из символов x0D x0A, так и просто из x0D. Например:
27.02.2019 00:04:00;27.02.2019 00:00:00;Payment;3464968222;USD;5.00;;;;;0957835959;;
27.02.2019 00:04:00;27.02.2019 00:00:00;Payment;3464968912;RUB;10.34;;;;;test@example.org;;
27.02.2019 00:11:00;27.02.2019 00:00:00;Payment;3464974548;EUR;4.72;;;;;ABC-12345;;
Дополнительные реквизиты платежа
Провайдер может предоставить дополнительные реквизиты (параметры) платежа для передачи в запросах.
Техническое название параметра должно отражать смысл параметра. Например, не допускаются такие названия, как a1, abc, для именования поля Имя пользователя. В техническом названии параметра допустимо использование только цифр, подчёркивания и строчных букв латинского алфавита (0-9_a-z).
Каждый дополнительный реквизит должен описываться следующим набором признаков:
- Название, отображаемое клиенту – текст, описывающий поле ввода на форме ввода реквизитов платежа, отображаемой клиенту.
- Описание – полное описание параметра.
- Регулярное выражение – используется для проверки правильности введённых данных.
- Маска ввода данных – используется в интерфейсе для упрощения ввода данных клиентом:
w– представляет буквенный символ;d– представляет цифру.
Пример:
| Техническое название параметра | Название, отображаемое пользователю | Описание | Регулярное выражение | Маска ввода данных |
|---|---|---|---|---|
| valid_thru | Срок истечения карты | Месяц и год истечения срока действия карты. Месяц и год включаются в срок действия карты. | \d{2}/\d{2} |
dd/dd |
Коды ошибок
Коды ошибок могут быть фатальные и нефатальные:
-
Фатальная ошибка означает, что повторная отправка запроса с теми же параметрами приведет к 100% повторению той же ошибки. В этом случае информационная система QIWI прекращает обработку запроса и завершает его с ошибкой.
Пример фатальной ошибки — отсутствие в ответе тега
<result>. -
Нефатальная ошибка означает, что повторение запроса с теми же параметрами через некоторый промежуток времени, возможно, приведет к успеху. При получении нефатальной ошибки информационная система QIWI будет повторять запросы, увеличивая интервал, пока операция не завершится успехом или фатальной ошибкой, либо пока не истечет срок жизни платежа (24 часа).
Пример нефатальной ошибки — отсутствие связи с сервером провайдера.
| Код | Комментарий | Фатальность |
|---|---|---|
| 0 | ОК | Нет |
| 1 | Временная ошибка. Повторите запрос позже | Нет |
| 4 | Неверный формат идентификатора абонента | Да |
| 5 | Идентификатор абонента не найден (Ошиблись номером) | Да |
| 7 | Прием платежа запрещен провайдером | Да |
| 8 | Прием платежа запрещен по техническим причинам | Да |
| 79 | Счет абонента не активен | Да |
| 90 | Проведение платежа не окончено | Нет |
| 241 | Сумма слишком мала | Да |
| 242 | Сумма слишком велика | Да |
| 243 | Невозможно проверить состояние счета | Да |
| 300 | Другая ошибка провайдера | Нет |