Вопросы
api_help@qiwi.com
NAV

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

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

Основные принципы работы интерфейса

Все запросы передаются методом GET, параметры передаются в пути запроса.

Передача информации о платеже провайдеру производится системой в два этапа – проверка статуса абонента и непосредственно проведение платежа. Также может добавляться предварительный этап получения дополнительных параметров платежа от провайдера, предоставляющего абоненту несколько сервисов, для информирования плательщика и добавления параметров платежа по выбору плательщика.

Тип запроса передается системой в переменной command – строка, принимающая значения check, pay или getInfo:

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

Все параметры обязательны в тех запросах, в которых они используются.

Параметр Формат Описание В каких запросах используется
txn_id Целое число длиной до 20 знаков Уникальный идентификатор платежа в системе QIWI Wallet. По этому идентификатору производится дальнейшая сверка взаиморасчетов и решение спорных вопросов. check, pay
sum Дробное число с точностью до сотых, в качестве разделителя используется . (точка). Если сумма представляет целое число, то оно все равно дополняется точкой и нулями, например – 152.00. Сумма платежа check, pay
ccy Код валюты Alpha-3 ISO 4217 Валюта платежа check, pay
txn_date ГГГГММДДЧЧММСС Дата платежа (под датой платежа в системе подразумевается дата получения запроса от клиента). По этой дате производится дальнейшая сверка взаиморасчётов между QIWI Wallet и провайдером.
Например, клиент отправил запрос в систему QIWI Wallet 31.12.2010 в 23:59:59, и система QIWI Wallet отправила свой запрос провайдеру 01.01.2011 в 00:00:05. Это может привести к проблеме сверки платежей, если система провайдера поместит транзакцию в следующий расчётный период. Чтобы избежать подобных проблем, QIWI Wallet предоставляет провайдеру оригинальную дату платежа.
pay
account Строка, содержащая буквы, цифры и спецсимволы, длиной до 200 символов Идентификатор абонента. Провайдер идентифицирует своего абонента по уникальному идентификатору (номер лицевого счета, телефона, логин и т.д.). Перед отправкой провайдеру, идентификатор проходит проверку корректности в соответствии с регулярным выражением, которое должен предоставить провайдер. check, pay, getInfo
extra[parameter_name] Допустимыми являются цифры (0-9), подчёркивание (_) и строчные буквы латинского алфавита (a-z) Дополнительные реквизиты платежа (экстра поля). Данные параметры могут быть использованы в случае, если платёж невозможно провести без дополнительных данных (одного идентификатора пользователя в системе провайдера недостаточно).
Например, идентификатор пользователя – номер кредитной карты, но для проведения платежа также нужно указать срок действия карты.
Перечень необходимых полей для передачи провайдеру необходимо указывать в заявке на подключение.
check, pay
prvId Целое число Идентификатор сервиса в общей системе провайдера. getInfo
parameter_name Формат имени и значения параметров указывается провайдером в заявке на подключение. Дополнительные параметры для идентификации абонента getInfo

Формат ответа

Провайдер должен вернуть ответ на запросы системе в формате XML. Общая структура ответа приведена на вкладке справа.

<?xml version="1.0" encoding="UTF-8"?>
<response>
  <osmp_txn_id>123323498</osmp_txn_id>
  <prv_txn>12369Bdkjh9</prv_txn>
  <sum>100.00</sum>
  <ccy>643</ccy>
  <fields>
    <field name="prv-date">2012-04-05T12:00:07</field>
  </fields>
  <type hasList="true" hasInfo="false" />
  <extra>
    <list>
      <field name=".."></field>
    </list>
    <info>
      <field name=".."></field>
    </info>
  </extra>
  <result>0</result>
  <comment></comment>
</response>

В случае если любой из запросов провайдеру завершается ошибкой, то провайдер возвращает код ошибки в соответствии с таблицей.

В информационной системе провайдера не должно содержаться двух успешно проведенных платежей с одним и тем же номером txn_id. Если система повторно присылает запрос с уже существующим в информационной системе провайдера идентификатором txn_id, то провайдер должен вернуть результат обработки предыдущего запроса.

В ответе могут присутствовать следующие теги:

Например, имеет место ситуация: клиент прислал в систему запрос 31.12.2010 в 23:59:59. Учитывая задержку на обработку данных и пересылку информации по каналам связи, провайдером платеж будет получен 1.01.2011 00:00:05 и, соответственно, учтен в системе провайдера в другом отчетном периоде. Чтобы при проведении сверок проблем с разными отчетными периодами не возникало, необходимо, чтобы провайдер возвращал дату, по которой производится учет в его системе.

Пример запроса на проверку состояния счета абонента и регистрацию платежа

Условия примера:

Платежное приложение провайдера payment_app.cgi, располагается по адресу service.someprv.ru, сервер поддерживает HTTPS соединения на порт 8443.

Для проверки состояния абонента система генерирует запрос (см. вкладку справа).

GET /payment_app.cgi?command=check&txn_id=1234567&
account=4957835959&sum=10.45&ccy=RUB HTTP/1.1
Host: service.someprv.ru:8443
Ответ провайдера
<?xml version="1.0" encoding="UTF-8"?>
<response>
<osmp_txn_id>1234567</osmp_txn_id>
<prv_txn>2016AB</prv_txn>
<sum>10.45</sum>
<ccy>RUB</ccy>
<result>0</result>
<comment>OK</comment>
</response>

Запрос содержит параметры:

Успешный ответ провайдера (см. вкладку справа).

Возвращение result=0 на запрос check свидетельствует о том, что лицевой счет абонента с соответствующим ему номером в поле account может быть пополнен на сумму, указанную в запросе в поле sum. После успешной проверки состояния счета абонента система переходит к формированию и отправке запроса на пополнение баланса (запрос pay).

В необязательном поле comment содержится служебный комментарий.

Пример запроса на пополнение лицевого счета

Условия примера:

Платежное приложение провайдера payment_app.cgi, располагается по адресу service.someprv.ru, сервер поддерживает HTTPS соединения на порт 8443.

Для подтверждения платежа система генерирует запрос (см. вкладку справа).

GET /payment_app.cgi?command=pay&txn_id=1234567&
txn_date=20110815120133&account=4957835959&sum=10.45&ccy=RUB HTTP/1.1
Host: service.someprv.ru:8443
Ответ провайдера
<?xml version="1.0" encoding="UTF-8"?>
<response>
<osmp_txn_id>1234567</osmp_txn_id>
<prv_txn>2016AB</prv_txn>
<sum>10.45</sum>
<ccy>RUB</ccy>
<result>0</result>
<comment>OK</comment>
<fields>
    <field name="prv-date">2011-08-15T12:06:45</field>
</fields>
</response>

Запрос содержит параметры:

Ответ провайдера см. на вкладке справа.

Возвращая result=0 на запрос pay, провайдер сообщает об успешном завершении операции пополнения баланса. Система полностью завершает обработку данной транзакции.

В необязательном поле comment содержится служебный комментарий.

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

Условия примера:

Платежное приложение провайдера payment_app.cgi, располагается по адресу service.someprv.ru, сервер поддерживает HTTPS соединения на порт 8443.

Для получения дополнительных данных платежа система генерирует запрос (см. вкладку справа).

GET /payment_app.cgi?command=getInfo&prvId=12345&
account=4957835959&name1=%26%30AB&name2=0 HTTP/1.1
Host: service.someprv.ru:8443
Ответ провайдера
<?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>

Запрос содержит параметры:

Ответ провайдера см. на вкладке справа.

Возвращение result=0 на запрос getInfo свидетельствует о том, что запрос выполнен успешно и дополнительные данные для отображения абоненту получены.

В необязательном поле comment содержится служебный комментарий.

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

До 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 Wallet, указанным в договоре, до 12:00 для выяснения ситуации и принятия решения.

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

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

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

Authorization: Basic ***

Здесь:

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

Заявка на подключение (образец)

  1. Юридическое наименование организации провайдера (как в договоре)

  2. Короткое название провайдера (для отображении в клиентском интерфейсе)

  3. Приглашение для ввода пользователя (для отображении в клиентском интерфейсе) (например «Введите номер»)

  4. URL платежного приложения (например, https://service.someprv.ru:8443/payment_app.cgi)

  5. Логин и пароль, если требуется basic-авторизация

  6. E-mail адрес для отправки ежедневных реестров

  7. Размер вознаграждения в %, перечисляемый QIWI Wallet за каждый платеж

  8. Регулярное выражение для проверки правильности идентификатора

  9. Несуществующий идентификатор в системе провайдера (данный идентификатор должен удовлетворять регулярному выражению, проверяющему правильность идентификаторов, но не должен существовать в системе; он будет использоваться при тестировании подключения, платежи на данный идентификатор во взаиморасчетах участвовать не будут)

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

  11. Серверный сертификат провайдера в формате X.509

  12. Клиентский сертификат для QIWI Wallet в формате PKCS12 (если требуется авторизация по клиентскому сертификату)

  13. E-mail адрес для обращений в случае технических проблем в работе шлюза

  14. Дополнительные реквизиты платежа

    • Техническое название параметра должно отражать смысл параметра. Например, не допускаются такие названия, как a1, abc, для именования поля “Имя пользователя”. В техническом названии параметра допустимо использование только цифр, подчёркивания и строчных букв латинского алфавита (0-9_a-z).
    • Название, отображаемое пользователю – текст, описывающий поле ввода на форме ввода реквизитов платежа, отображаемой пользователю.
    • Описание – полное описание параметра.
    • Регулярное выражение – используется для проверки правильности введённых данных.
    • Маска ввода данных – используется в интерфейсе для упрощения ввода данных пользователем:
      • w – представляет буквенный символ;
      • d – представляет цифру.

Пример:

Техническое название параметра Название, отображаемое пользователю Описание Регулярное выражение Маска ввода данных
valid_thru Срок истечения карты Месяц и год истечения срока действия карты. Месяц и год включаются в срок действия карты. \d{2}/\d{2} dd/dd

Список кодов завершения

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

Знак + в столбце “фатальность” указывает на признак фатальности ошибки. Для системы QIWI Wallet фатальная ошибка означает, что повторная отправка запроса с теми же параметрами приведет к 100% повторению той же ошибки – следовательно, система прекращает обработку клиентского запроса и завершает его с ошибкой.

Нефатальная ошибка означает для системы, что повторение запроса с теми же параметрами через некоторый промежуток времени, возможно, приведет к успеху. Система будет повторять запросы, завершающиеся нефатальной ошибкой, постоянно увеличивая интервал, пока операция не завершится успехом или фатальной ошибкой, либо пока не истечет срок жизни запроса – 24 часа.

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

Отсутствие в ответе элемента (некорректный XML, страница Service temporarily unavailable и т.д.) также является нефатальной ошибкой.

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