Вопросы
bss@qiwi.com
NAV Navbar
Примеры

Унифицированный интерфейс обмена информацией

Интерфейс предназначен для обмена информацией с кредитной организацией (далее — Контрагент), подключенной как провайдер к QIWI.

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

Каждый платеж в сервисе QIWI имеет уникальный идентификатор, который передается Контрагенту в виде двух переменных:

По комбинации этих двух переменных производится дальнейшая сверка взаиморасчетов и решение спорных вопросов.

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

Ознакомьтесь также с рекомендациями по интеграции с интерфейсом QIWI:

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

  1. Интерфейс должен принимать запросы по протоколу HTTP или HTTPS с IP-адресов подсетей:
  1. Интерфейс должен обрабатывать запросы HTTP GET, HTTP POST.
  2. Интерфейс должен формировать ответ на запрос в формате XML в кодировке UTF-8.
  3. Скорость ответа не должна превышать 60 секунд, в противном случае сервис QIWI разрывает соединение по таймауту.
  4. Если предполагаемое количество платежей за услуги подключаемого провайдера ожидается интенсивным (до 10 платежей в минуту и более), необходимо, чтобы интерфейс поддерживал многопоточную коммуникацию до 10-15 одновременных соединений.

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

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

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

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

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

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

Передача информации о платеже Контрагенту производится системой в два этапа:

  1. Проверка возможности проведения платежа (авторизация).
  2. Проведение платежа (регистрация).

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

Протокол содержит дополнительные методы, не влияющие на процесс платежа:

Реализация этих методов опциональна.

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

Запрос предназначен для проверки идентификатора Клиента и получения дополнительной информации о Клиенте. При получении запроса провайдер:

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

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

<?xml version="1.0" encoding="UTF-8"?>
<request command="getinfo">
  <verno>342</verno>
  <auth>
    <login>qiwi</login>
    <psw>qiwi</psw>
  </auth>
  <doc>
    <sysid>26090</sysid>
    <sysno>999902885370117</sysno>
    <doctime>20211031124845</doctime>
    <mesid>4444</mesid>
    <docno/>
    <rem_key/>
  </doc>
  <crypt>
    <cryp_prov></cryp_prov>
    <sign></sign>
    <keyid></keyid>
    <encrypt>0</encrypt>
  </crypt>
</request>
Параметр Формат Обяз. Описание
command getinfo ✓ Идентификация типа запроса: запрос на получение дополнительных данных платежа для абонента. Всегда равен getInfo
verno varchar2(30) ✓ Версия протокола
auth   ✓ Блок с информацией об авторизации
login varchar2(30) ✓ Логин
psw varchar2(30) ✓ Пароль
doc   ✓ Блок с информацией о документе
sysid varchar2(12) ✓ Код платежной системы
sysno varchar2(24) ✓ Номер транзакции в платежной системе
doctime date (yyyymmddhh(24)mmss) ✓ Время регистрации транзакции в платежной системе
mesid varchar2(5) ✓ Тип платежа
docno varchar2(20)   Номер документа
rem_key varchar2(30) ✓ Идентификатор плательщика в информационной системе Контрагента
crypt     Блок с электронной подписью
cryp_prov varchar2(20)   Криптопровайдер
sign varchar2(50)   Подпись платежа
keyid varchar2(20)   Ключ
encrypt number(1)   Флаг "зашифрован" (1) / "не зашифрован" (0)

Параметры ответа

Пример ответа

<?xml version="1.0" encoding="UTF-8"?>
<response command="getinfo">
  <verno>342</verno>
  <doc>
    <id>
      <sysid>26090</sysid>
      <sysno>999902885370117</sysno>
      <doctime>20211031124845</doctime>
    </id>
    <mesid>4444</mesid>
    <docno></docno>
    <rem_name></rem_name>
    <rem_name2></rem_name2>
    <rem_name3></rem_name3>
    <rem_address></rem_address>
    <rem_key></rem_key>
    <result></result>
    <comment></comment>
    <timeout></timeout>
    <extra>
      <field1></field1>
      <field2></field2>
      <fieldN></fieldN>
    </extra>
  </doc>
  <crypt>
    <cryp_prov></cryp_prov>
    <sign></sign>
    <keyid></keyid>
    <encrypt></encrypt>
  </crypt>
</response>

В ответе интерфейс Контрагента должен вернуть XML-документ с блоком <response> и следующими тегами:

Параметр Формат Обяз. Описание
command getinfo ✓ Идентификация типа запроса: запрос на получение информации о плательщике. Всегда равен getinfo
verno varchar2(30) ✓ Версия протокола. Повтор значения тега из запроса.
doc   ✓ Блок с информацией о документе
sysid varchar2(12) ✓ Код платежной системы. Повтор значения тега из запроса.
sysno varchar2(24) ✓ Номер транзакции в платежной системе. Повтор значения тега из запроса.
doctime date (yyyymmddhh(24)mmss) ✓ Время регистрации транзакции в платежной системе
mesid varchar2(5) ✓ Тип платежа
docno varchar2(20)   Номер документа
rem_name varchar2(254)   Название/фамилия плательщика
rem_name2 varchar2(254)   Имя плательщика
rem_name3 varchar2(254)   Отчество плательщика
rem_address varchar2(254)   Адрес плательщика
rem_key varchar2(30) ✓ Идентификатор плательщика в информационной системе Контрагента. Повтор значения тега из запроса.
result number(3) ✓ Код завершения
comment varchar2(254)   Расшифровка кода завершения
timeout number   Задержка отправки повторного запроса в минутах
extra     Блок с дополнительной информацией
field1, field2, fieldN varchar2(254)   Дополнительная информация
crypt     Блок с электронной подписью
cryp_prov varchar2(20)   Криптопровайдер
sign varchar2(50)   Подпись платежа
keyid varchar2(20)   Ключ
encrypt number(1)   Флаг "зашифрован" (1) / "не зашифрован" (0)

Проверка возможности проведения платежа (авторизация)

При получении запроса Контрагент должен выполнить внутренние проверки на возможность проведения платежа.

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

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

<?xml version="1.0" encoding="UTF-8"?>
<request command="check">
  <verno>342</verno>
  <auth>
    <login>qiwi</login>
    <psw>qiwi</psw>
  </auth>
  <doc>
    <id>
      <sysid>26090</sysid>
      <sysno>999902885370117</sysno>
      <doctime>20211031124845</doctime>
      <prov_code>044525521</prov_code>
    </id>
    <docattr>
      <mesid>4444</mesid>
      <docno/>
      <amount>100</amount>
      <comission/>
      <remarks/>
      <cbc/>
      <tax_no/>
      <tax_type/>
      <doc_type>3</doc_type>
    </docattr>
    <remitent>
      <rem_name/>
      <rem_nam2/>
      <rem_nam3/>
      <rem_tax/>
      <rem_kpp/>
      <rem_okato/>
      <rem_phone/>
      <rem_pob/>
      <rem_dob/>
      <rem_dcm_type/>
      <rem_dcm_serial_no/>
      <rem_dcm_no/>
      <rem_dcm_date/>
      <rem_dcm_issue_where/>
      <rem_address></rem_address>
      <rem_mfo>044585416</rem_mfo>
      <rem_acc></rem_acc>
      <rem_deb></rem_deb>
      <rem_cardno></rem_cardno>
      <rem_cardexp></rem_cardexp>
      <rem_key></rem_key>
      <rem_agrno></rem_agrno>
      <rem_extrainfo></rem_extrainfo>
    </remitent>
    <recipient>
      <rec_name></rec_name>
      <rec_nam2></rec_nam2>
      <rec_nam3></rec_nam3>
      <rec_tax></rec_tax>
      <rec_kpp></rec_kpp>
      <rec_okato></rec_okato>
      <rec_phone></rec_phone>
      <rec_pob></rec_pob>
      <rec_dob></rec_dob>
      <rec_dcm_type></rec_dcm_type>
      <rec_dcm_serial_no></rec_dcm_serial_no>
      <rec_dcm_no></rec_dcm_no>
      <rec_dcm_date></rec_dcm_date>
      <rec_dcm_issue_where></rec_dcm_issue_where>
      <rec_address></rec_address>
      <rec_mfo>044525521</rec_mfo>
      <rec_acc></rec_acc>
      <rec_cre>40817810700470049428</rec_cre>
      <rec_cardno></rec_cardno>
      <rec_cardexp/>
      <rec_key/>
      <rec_agrno/>
      <rec_extrainfo></rec_extrainfo>
    </recipient>
    <point>
      <terpfp></terpfp>
      <terid>9476886</terid>
      <terkvi/>
      <tercity>http://qiwi.ru</tercity>
      <teraddr></teraddr>
      <teragnt></teragnt>
    </point>
  </doc>
  <crypt>
    <cryp_prov/>
    <sign/>
    <keyid>qiwi</keyid>
    <encrypt>0</encrypt>
  </crypt>
</request>
Параметр Формат Обяз. Описание
command check ✓ Идентификация типа запроса: запрос проверки возможности проведения платежа. Всегда равен check
verno varchar2(30) ✓ Версия протокола
auth   ✓ Блок с информацией об авторизации
login varchar2(30) ✓ Логин
psw varchar2(30) ✓ Пароль
doc   ✓ Блок с информацией о документе
id   ✓ Блок с информацией об идентификации документа
sysid varchar2(12) ✓ Код платежной системы
sysno varchar2(24) ✓ Номер транзакции в платежной системе
doctime date (yyyymmddhh(24)mmss) ✓ Время регистрации транзакции в платежной системе
prov_code varchar2(9) ✓ Код Контрагента
docattr   ✓ Блок информации об атрибутах документа
mesid varchar2(5) ✓ Тип платежа
docno varchar2(20)   Номер документа
amount number ✓ Сумма платежа в копейках
comission number   Комиссия платежа в копейках
remarks varchar2(160)   Примечание
cbc varchar2(20)   Код бюджетной классификации
tax_no varchar2(20)   Номер налогового документа
doc_type varchar2(4)   Тип документа: 1 — пополнение счета, 2 — погашение кредита, 3-пополнение банковской карты
tax_type varchar2(2)   Тип налогового документа
remittent     Блок с информацией о плательщикe
rem_name varchar2(254)   Название плательщика/Фамилия
rem_nam2 varchar2(254)   Имя плательщика
rem_nam3 varchar2(254)   Отчество плательщика
rem_tax varchar2(12)   ИНН плательщика
rem_kpp varchar2(26)   КПП плательщика
rem_okato varchar2(26)   ОКАТО плательщика
rem_phone number   Телефон плательщика
rem_pob varchar2(254)   Место рождения плательщика
rem_dob date(yyyymmdd)   Дата рождения плательщика
rem_dcm_type varchar2(30)   Тип документа плательщика
rem_dcm_serial_no varchar2(40)   Серийный номер документа плательщика
rem_dcm_no varchar2(40)   Номер документа плательщика
rem_dcm_date date (yyyymmdd)   Дата получения документа плательщика
rem_dcm_issue_where varchar2(254)   Кем выдан документ плательщика
rem_address varchar2(254)   Адрес плательщика
rem_mfo varchar2(9) ✓ БИК банка плательщика
rem_acc varchar2(25)   Корсчет банка плательщика
rem_deb varchar2(25)   Счет плательщика в банке плательщика
rem_cardno varchar2(20)   Номер/маска карты плательщика
rem_cardexp varchar2(4)   Срок действия карты плательщика
rem_key varchar2(30)   Идентификатор плательщика в банке плательщика
rem_agrno varchar2(50)   Идентификатор договора плательщика
rem_extrainfo varchar2(512)   Доп. информация плательщика
recipient     Блок с информацией о получателе
reс_name varchar2(254) ✓ Название получателя/Фамилия
reс_nam2 varchar2(254)   Имя получателя
reс_nam3 varchar2(254)   Отчество получателя
reс_tax varchar2(12)   ИНН получателя
reс_kpp varchar2(26)   КПП получателя
reс_okato varchar2(26)   ОКАТО получателя
reс_phone number   Телефон получателя
reс_pob varchar2(254)   Место рождения получателя
reс_dob date (yyyymmdd)   Дата рождения получателя
reс_dcm_type varchar2(30)   Тип документа получателя
reс_dcm_serial_no varchar2(40)   Серийный номер документа получателя
reс_dcm_no varchar2(40)   Номер документа получателя
reс_dcm_date date (yyyymmdd)   Дата получения документа получателя
reс_dcm_issue_where varchar2(254)   Кем выдан документ получателя
reс_address varchar2(254)   Адрес получателя
reс_mfo varchar2(9) ✓ БИК банка получателя
reс_acc varchar2(25)   Корсчет банка получателя
reс_cre varchar2(25)   Счет получателя в банке получателя
reс_cardno varchar2(20)   Номер/маска карты получателя
reс_cardexp varchar2(4)   Срок действия карты получателя
reс_key varchar2(30)   Идентификатор получателя в банке получателя
reс_agrno varchar2(50)   Идентификатор договора получателя
reс_extrainfo varchar2(512)   Доп. информация получателя
point     Блок информации о платежном терминале
terpfp varchar2(50)   Номер ПФП
terid varchar2(20) ✓ Идентификатор АСО
terkvi number   Номер платежной квитанции
tercity varchar2(150)   Город расположения АСО
teraddr varchar2(254)   Место расположения АСО
teragnt varchar2(254)   Название владельца АСО
crypt     Блок с электронной подписью
cryp_prov varchar2(20)   Криптопровайдер
sign varchar2(50)   Подпись платежа
keyid varchar2(20)   Ключ
encrypt number(1)   Флаг "зашифрован" (1) / "не зашифрован" (0)

Параметры ответа

Пример ответа

<?xml version="1.0" encoding="UTF-8"?>
<response command="check">
  <verno>342</verno>
  <doc>
    <sysid>26090</sysid>
    <sysno>999902885370117</sysno>
    <prv_id>11137584</prv_id>
    <doctime>20211031124845</doctime>
    <amount>100</amount>
    <comission></comission>
    <rec_name></rec_name>
    <rec_name2></rec_name2>
    <rec_name3></rec_name3>
    <rec_cardno></rec_cardno>
    <rec_cre></rec_cre>
    <rec_agrno></rec_agrno>
    <rec_key></rec_key>
    <result>0</result>
    <comment>OK</comment>
    <timeout></timeout>
    <extra>
      <field1></field1>
      <field2></field2>
    </extra>
  </doc>
  <crypt>
    <cryp_prov></cryp_prov>
    <sign></sign>
    <keyid>qiwi</keyid>
    <encrypt>0</encrypt>
  </crypt>
</response>

В ответе интерфейс Контрагента должен вернуть XML-документ с блоком <response> и следующими тегами:

Параметр Формат Обяз. Описание
command check ✓ Идентификация типа запроса: запрос проверки возможности проведения платежа. Всегда равен check
verno varchar2(30) ✓ Версия протокола
doc   ✓ Блок с информацией о документе
sysid varchar2(12) ✓ Код платежной системы
sysno varchar2(24) ✓ Номер транзакции в платежной системе
doctime date (yyyymmddhh(24)mmss) ✓ Время регистрации транзакции в платежной системе
prv_id varchar2(20) ✓ Номер транзакции в информационной системе Контрагента. Уникальный номер операции пополнения баланса получателя (в базе Контрагента), целое число длиной до 20 знаков
amount number ✓ Сумма платежа в копейках
comission number   Комиссия платежа в копейках
reс_name varchar2(254) ✓ Название получателя/Фамилия
reс_nam2 varchar2(254)   Имя получателя
reс_nam3 varchar2(254)   Отчество получателя
reс_cre varchar2(25)   Счет получателя в банке получателя
reс_cardno varchar2(20)   Номер/маска карты получателя
reс_key varchar2(30)   Идентификатор получателя в банке получателя
reс_agrno varchar2(50)   Идентификатор договора получателя
result number(3) ✓ Код завершения
comment varchar2(254) ✓ Расшифровка кода завершения
timeout number   Задержка отправки повторного запроса в минутах. Время, через которое Контрагент рекомендует повторить запрос, если в результате выполнения его ранее получен нефатальный код завершения, отличный от 0.
extra     Блок с дополнительной информацией
field1, field2, fieldN varchar2(254)   Дополнительная информация, которую можно передать информационной системе Контрагента. Эта информация может быть показана пользователю при совершении платежа.
crypt     Блок с электронной подписью
cryp_prov varchar2(20)   Криптопровайдер
sign varchar2(50)   Подпись платежа
keyid varchar2(20)   Ключ
encrypt number(1)   Флаг "зашифрован" (1) / "не зашифрован" (0)

Возвращение <result>0</result> на запрос check свидетельствует о том, что платеж с соответствующей ему уникальной парой sysid и sysno может быть зарегистрирован на сумму, указанную в запросе. После успешной проверки возможности проведения платежа система переходит к формированию и отправке запроса на регистрацию платежа.

Регистрация платежа

При получении запроса Контрагент должен произвести регистрацию платежа.

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

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

<?xml version="1.0" encoding="UTF-8"?>
<request command="pay">
  <verno>342</verno>
  <auth>
    <login>qiwi</login>
    <psw>qiwi</psw>
  </auth>
  <doc>
    <id>
      <sysid>26090</sysid>
      <sysno>999902885370117</sysno>
      <doctime>20211031124845</doctime>
      <prov_code>044525521</prov_code>
    </id>
    <docattr>
      <mesid>4444</mesid>
      <docno></docno>
      <amount>100</amount>
      <comission></comission >
      <remarks></remarks>
      <cbc></cbc>
      <tax_no></tax_no>
      <tax_type></tax_type>
      <doc_type>3<doc_type>
    </docattr>
    <remitent>
      <rem_name></rem_name>
      <rem_nam2></rem_nam2>
      <rem_nam3></rem_nam3>
      <rem_tax></rem_tax>
      <rem_kpp></rem_kpp>
      <rem_okato></rem_okato>
      <rem_phone></rem_phone>
      <rem_pob></rem_pob>
      <rem_dob></rem_dob>
      <rem_dcm_type></rem_dcm_type>
      <rem_dcm_serial_no></rem_dcm_serial_no>
      <rem_dcm_no></rem_dcm_no>
      <rem_dcm_date></rem_dcm_date>
      <rem_dcm_issue_where></rem_dcm_issue_where>
      <rem_address></rem_address>
      <rem_mfo>044585416</rem_mfo>
      <rem_acc></rem_acc>
      <rem_deb></rem_deb>
      <rem_cardno></rem_cardno>
      <rem_cardexp></rem_cardexp>
      <rem_key></rem_key>
      <rem_agrno></rem_agrno>
      <rem_extrainfo></rem_extrainfo>
    </remitent>
    <recipient>
      <rec_name></rec_name>
      <rec_nam2></rec_nam2>
      <rec_nam3></rec_nam3>
      <rec_tax></rec_tax>
      <rec_kpp></rec_kpp>
      <rec_okato></rec_okato>
      <rec_phone></rec_phone>
      <rec_pob></rec_pob>
      <rec_dob></rec_dob>
      <rec_dcm_type></rec_dcm_type>
      <rec_dcm_serial_no></rec_dcm_serial_no>
      <rec_dcm_no></rec_dcm_no>
      <rec_dcm_date></rec_dcm_date>
      <rec_dcm_issue_where></rec_dcm_issue_where>
      <rec_address></rec_address>
      <rec_mfo>044525521</rec_mfo>
      <rec_acc></rec_acc>
      <rec_cre>40817810700470049428</rec_cre>
      <rec_cardno></rec_cardno>
      <rec_cardexp></rec_cardexp>
      <rec_key></rec_key>
      <rec_agrno></rec_agrno>
      <rec_extrainfo></rec_extrainfo>
    </recipient>
    <point>
      <terpfp></terpfp>
      <terid>9476886</terid>
      <terkvi></terkvi>
      <tercity>http://qiwi.ru</tercity>
      <teraddr></teraddr>
      <teragnt></teragnt>
    </point>
  </doc>
  <crypt>
    <cryp_prov></cryp_prov>
    <sign></sign>
    <keyid>qiwi</keyid>
    <encrypt>0</encrypt>
  </crypt>
</request>
Параметр Формат Условие Описание
command pay ✓ Идентификация типа запроса: запрос регистрации платежа. Всегда равен pay
verno varchar2(30) ✓ Версия протокола
auth   ✓ Блок с информацией об авторизации
login varchar2(30) ✓ Логин
psw varchar2(30) ✓ Пароль
doc   ✓ Блок с информацией о документе
id   ✓ Блок с информацией об идентификации документа
sysid varchar2(12) ✓ Код платежной системы
sysno varchar2(24) ✓ Номер транзакции в платежной системе
doctime date (yyyymmddhh(24)mmss) ✓ Время регистрации транзакции в платежной системе
prov_code varchar2(9) ✓ Код Контрагента
docattr     Блок информации об атрибутах документа
mesid varchar2(5) ✓ Тип платежа
docno varchar2(20)   Номер документа
amount number ✓ Сумма платежа в копейках
comission number ✓ Комиссия платежа в копейках
remarks varchar2(160)   Примечание
cbc varchar2(20)   Код бюджетной классификации
tax_no varchar2(20)   Номер налогового документа
doc_type varchar2(4)   Тип документа: 1 — пополнение счета, 2 — погашение кредита, 3-пополнение банковской карты
tax_type varchar2(2)   Тип налогового документа
remittent     Блок с информацией о плательщикe
rem_name varchar2(254)   Название плательщика/Фамилия
rem_nam2 varchar2(254)   Имя плательщика
rem_nam3 varchar2(254)   Отчество плательщика
rem_tax varchar2(12)   ИНН плательщика
rem_kpp varchar2(26)   КПП плательщика
rem_okato varchar2(26)   ОКАТО плательщика
rem_phone number   Телефон плательщика
rem_pob varchar2(254)   Место рождения плательщика
rem_dob date(yyyymmdd)   Дата рождения плательщика
rem_dcm_type varchar2(30)   Тип документа плательщика
rem_dcm_serial_no varchar2(40)   Серийный номер документа плательщика
rem_dcm_no varchar2(40)   Номер документа плательщика
rem_dcm_date date (yyyymmdd)   Дата получения документа плательщика
rem_dcm_issue_where varchar2(254)   Кем выдан документ плательщика
rem_address varchar2(254)   Адрес плательщика
rem_mfo varchar2(9) ✓ БИК банка плательщика
rem_acc varchar2(25)   Корсчет банка плательщика
rem_deb varchar2(25)   Счет плательщика в банке плательщика
rem_cardno varchar2(20)   Номер/маска карты плательщика
rem_cardexp varchar2(4)   Срок действия карты плательщика
rem_key varchar2(30)   Идентификатор плательщика в банке плательщика
rem_agrno varchar2(50)   Идентификатор договора плательщика
rem_extrainfo varchar2(512)   Доп. информация плательщика
recipient     Блок с информацией о получателе
reс_name varchar2(254) ✓ Название получателя/Фамилия
reс_nam2 varchar2(254)   Имя получателя
reс_nam3 varchar2(254)   Отчество получателя
reс_tax varchar2(12)   ИНН получателя
reс_kpp varchar2(26)   КПП получателя
reс_okato varchar2(26)   ОКАТО получателя
reс_phone number   Телефон получателя
reс_pob varchar2(254)   Место рождения получателя
reс_dob date (yyyymmdd)   Дата рождения получателя
reс_dcm_type varchar2(30)   Тип документа получателя
reс_dcm_serial_no varchar2(40)   Серийный номер документа получателя
reс_dcm_no varchar2(40)   Номер документа получателя
reс_dcm_date date (yyyymmdd)   Дата получения документа получателя
reс_dcm_issue_where varchar2(254)   Кем выдан документ получателя
reс_address varchar2(254)   Адрес получателя
reс_mfo varchar2(9) ✓ БИК банка получателя
reс_acc varchar2(25)   Корсчет банка получателя
reс_cre varchar2(25)   Счет получателя в банке получателя
reс_cardno varchar2(20)   Номер/маска карты получателя
reс_cardexp varchar2(4)   Срок действия карты получателя
reс_key varchar2(30)   Идентификатор получателя в банке получателя
reс_agrno varchar2(50)   Идентификатор договора получателя
reс_extrainfo varchar2(512)   Доп. информация получателя
point     Блок информации о платежном терминале
terpfp varchar2(50)   Номер ПФП
terid varchar2(20) ✓ Идентификатор АСО
terkvi number   Номер платежной квитанции
tercity varchar2(150)   Город расположения АСО
teraddr varchar2(254)   Место расположения АСО
teragnt varchar2(254)   Название владельца АСО
crypt     Блок с электронной подписью
cryp_prov varchar2(20)   Криптопровайдер
sign varchar2(50)   Подпись платежа
keyid varchar2(20)   Ключ
encrypt number(1)   Флаг "зашифрован" (1) / "не зашифрован" (0)

Параметры ответа

Пример ответа

<?xml version="1.0" encoding="UTF-8"?>
<response command="pay">
  <verno>342</verno>
  <doc>
    <sysid>26090</sysid>
    <sysno>999902885370117</sysno>
    <prv_id>11132331</prv_id>
    <doctime>20211031124845</doctime>
    <amount></amount>
    <comission></comission>
    <rec_name></rec_name>
    <rec_name2></rec_name2>
    <rec_name3></rec_name3>
    <rec_cardno></rec_cardno>
    <rec_cre></rec_cre>
    <rec_agrno></rec_agrno>
    <rec_key></rec_key>
    <result>0</result>
    <comment>OK</comment>
    <timeout></timeout>
    <extra>
      <field1></field1>
      <field2></field2>
    </extra>
  </doc>
  <crypt>
    <cryp_prov></cryp_prov>
    <sign></sign>
    <keyid>qiwi</keyid>
    <encrypt>0</encrypt>
  </crypt>
</response>

В ответе интерфейс Контрагента должен вернуть XML-документ с блоком <response> и следующими тегами:

Параметр Формат Обяз. Описание
command pay ✓ Идентификация типа запроса: запрос проверки возможности проведения платежа. Всегда равен pay
verno varchar2(30) ✓ Версия протокола
doc   ✓ Блок с информацией о документе
sysid varchar2(12) ✓ Код платежной системы
sysno varchar2(24) ✓ Номер транзакции в платежной системе
doctime date (yyyymmddhh(24)mmss) ✓ Время регистрации транзакции в платежной системе
prv_id varchar2(20) ✓ Номер транзакции в информационной системе Контрагента. Уникальный номер операции пополнения баланса получателя (в базе Контрагента), целое число длиной до 20 знаков
amount number ✓ Сумма платежа в копейках
comission number ✓ Комиссия платежа в копейках
reс_name varchar2(254) ✓ Название получателя/Фамилия
reс_nam2 varchar2(254)   Имя получателя
reс_nam3 varchar2(254)   Отчество получателя
reс_cre varchar2(25)   Счет получателя в банке получателя
reс_cardno varchar2(20)   Номер/маска карты получателя
reс_key varchar2(30)   Идентификатор получателя в банке получателя
reс_agrno varchar2(50)   Идентификатор договора получателя
result number(3) ✓ Код завершения
comment varchar2(254) ✓ Расшифровка кода завершения
timeout number   Задержка отправки повторного запроса в минутах. Время, через которое Контрагент рекомендует повторить запрос, если в результате выполнения его ранее получен нефатальный код завершения, отличный от 0.
extra     Блок с дополнительной информацией
field1, field2, fieldN varchar2(254)   Дополнительная информация, которую можно передать информационной системе Контрагента. Эта информация может быть показана пользователю при совершении платежа.
crypt     Блок с электронной подписью
cryp_prov varchar2(20)   Криптопровайдер
sign varchar2(50)   Подпись платежа
keyid varchar2(20)   Ключ
encrypt number(1)   Флаг "зашифрован" (1) / "не зашифрован" (0)

Возвращение <result>0</result> на запрос pay свидетельствует о том, что Контрагент успешно завершил операцию регистрации платежа. В этом случае QIWI полностью завершает обработку данной транзакции.

Отмена регистрации платежа

При получении запроса Контрагент должен произвести отмену регистрации платежа.

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

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

<?xml version="1.0" encoding="UTF-8"?>
<request command="cancel">
  <verno>342</verno>
  <auth>
    <login>qiwi</login>
    <psw>qiwi</psw>
  </auth>
  <doc>
    <sysid>22454</sysid>
    <sysno>09343439921</sysno>
    <doctime>20211031124845</doctime>
    <prov_code>044525521</prov_code>
    <prv_id>113242434</prv_id>
    <reason></reason>
    <amount>95</amount>
  </doc>
  <crypt>
    <cryp_prov></cryp_prov>
    <sign></sign>
    <keyid>qiwi</keyid>
    <encrypt>0</encrypt>
  </crypt>
</request>
Параметр Формат Условие Описание
command cancel ✓ Идентификация типа запроса: запрос отмены регистрации платежа. Всегда равен cancel
verno varchar2(30) ✓ Версия протокола
auth   ✓ Блок с информацией об авторизации
login varchar2(30) ✓ Логин
psw varchar2(30) ✓ Пароль
doc   ✓ Блок с информацией о документе
sysid varchar2(12) ✓ Код платежной системы
sysno varchar2(24) ✓ Номер транзакции в платежной системе
doctime date (yyyymmddhh(24)mmss) ✓ Время регистрации транзакции в платежной системе
prov_code varchar2(9) ✓ Код Контрагента
prv_id varchar2(20)   Уникальный номер операции пополнения баланса получателя (в базе Контрагента)
reason varchar2(160) ✓ Причины отмены
docno varchar2(20) ✓ Номер документа
amount number ✓ Сумма платежа в копейках
crypt     Блок с электронной подписью
cryp_prov varchar2(20)   Криптопровайдер
sign varchar2(50)   Подпись платежа
keyid varchar2(20)   Ключ
encrypt number(1)   Флаг "зашифрован" (1) / "не зашифрован" (0)

Параметры ответа

Пример ответа

<?xml version="1.0" encoding="UTF-8"?>
<response command="cancel">
  <verno>342</verno>
  <doc>
    <sysid>22454</sysid>
    <sysno>09343439921</sysno>
    <doctime>20211031124845</doctime>
    <prv_id>113242434</prv_id>
    <docno></docno>
    <amount>95</amount>
    <result></result>
    <comment></comment>
    <extra>
      <field1></field1>
      <field2></field2>
    </extra>
  </doc>
  <crypt>
    <cryp_prov></cryp_prov>
    <sign></sign>
    <keyid>qiwi</keyid>
    <encrypt>0</encrypt>
  </crypt>
</response>

В ответе интерфейс Контрагента должен вернуть XML-документ с блоком <response> и следующими тегами:

Параметр Формат Обяз. Описание
command cancel ✓ Идентификация типа запроса: запрос проверки возможности проведения платежа. Всегда равен cancel
verno varchar2(30) ✓ Версия протокола
doc   ✓ Блок с информацией о документе
sysid varchar2(12) ✓ Код платежной системы
sysno varchar2(24) ✓ Номер транзакции в платежной системе
docno varchar2(20)   Номер документа
doctime date (yyyymmddhh(24)mmss) ✓ Время регистрации транзакции в платежной системе
prv_id varchar2(20)   Уникальный номер операции пополнения баланса получателя (в базе Контрагента), целое число длиной до 20 знаков
amount number ✓ Сумма платежа в копейках
result number(3) ✓ Код завершения
comment varchar2(254)   Расшифровка кода завершения
timeout number   Задержка отправки повторного запроса в минутах. Время, через которое Контрагент рекомендует повторить запрос, если в результате выполнения его ранее получен нефатальный код завершения, отличный от 0.
extra     Блок с дополнительной информацией
field1, field2, fieldN varchar2(254)   Дополнительная информация, которую можно передать информационной системе Контрагента. Эта информация может быть показана пользователю при совершении платежа.
crypt     Блок с электронной подписью
cryp_prov varchar2(20)   Криптопровайдер
sign varchar2(50)   Подпись платежа
keyid varchar2(20)   Ключ
encrypt number(1)   Флаг "зашифрован" (1) / "не зашифрован" (0)

Возвращение <result>0</result> на запрос cancel свидетельствует о том, что Контрагент успешно отменил операцию. В этом случае QIWI отменяет платеж.

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

Код Комментарий Фатальность
0 ОК Нет
100 ЭП отправителя неверна Да
101 Истек срок действия ключа отправителя Да
102 Ключ отправителя не зарегистрирован Да
103 Ключ отправителя блокирован Да
104 ЭП/АСП плательщика неверна Да
105 Ключ плательщика блокирован Да
106 Неверный логин/пароль при подключении к серверу Да
109 Подозрение в терроризме Да
110 Необрабатываемый тип сообщения Да
111 Неверный тип документа Да
112 Неверный тип платежа Да
119 Пополнение валютных счетов и карт запрещено Да
120 Неверный БИК плательщика Да
121 Неверный счет или БИК плательщика Да
122 Неверный номер или срок действия карты плательщика Да
123 Неверный ИНН плательщика Да
124 Неверный идентификатор плательщика Да
125 Счет плательщика блокирован Да
126 Карта плательщика блокирована Да
127 Ошибка в сроке действия карты плательщика Да
128 Истек срок действия карты плательщика Да
129 Неверный номер договора плательщика Да
130 Отсутствует ФИО, место и/или дата рождения плательщика Да
131 Отсутствует или неверный номер терминала Да
132 Отсутствует адрес терминала Да
133 Отсутствует или неверный номер агента терминала Да
134 Отсутствует наименование агента терминала Да
135 Отсутствует код платежной системы Да
136 Отсутствует внутренний номер платежа Да
137 Неверный формат поля "дата рождения" Да
138 Неверный формат поля "дата учета платежа" Да
139 Не заполнено поле oper_type Да
140 Неверный БИК получателя Да
141 Неверный счет или БИК получателя Да
142 Неверный номер карты получателя Да
143 Неверный ИНН получателя Да
144 Неверный Идентификатор получателя Да
145 Счет получателя блокирован Да
146 Карта получателя блокирована Да
147 Ошибка в сроке действия карты получателя Да
148 Истек срок действия карты получателя Да
149 Неверный номер договора получателя Да
150 Неверное имя/ФИО получателя Да
151 Сумма слишком мала Да
152 Сумма слишком велика/Превышен лимит платежей в день Да
153 Неверный формат поля "сумма платежа" Да
154 Неверный формат поля "комиссия" Да
155 Сумма комиссии больше суммы платежа Да
156 Превышен суточный лимит суммы платежей на один номер счета/карты/договора Да
157 Сумма платежа = 0 Да
159 Невозможно идентифицировать получателя платежа Да
160 Отвергнут оператором банка отправителя Да
161 Отвергнут оператором банка получателя Да
162 Не заполнен номер телефона Да
171 Запрос check не найден или выполнен с ошибкой Да
172 Неверный тип платежа Да
181 Платеж невозможно отменить Да
189 Платеж принят на исполнение. Ожидается подтверждение Да
190 Платеж принят на обработку Да
191 Платеж невозможно отменить Да
192 Истек срок действия подарочного сертификата Да
201 Помещен в архив Да
299 Блокировка банка-кредитора Да
300 По техническим причинам данная операция не может быть выполнена. Для осуществления платежа обратитесь, пожалуйста, в свой обслуживающий банк Да
301 Прочие ошибки системы Да

Реестры платежей

Передача реестров платежей выполняется по электронной почте с использованием одного из следующих средств шифрования:

Схема взаимодействия по реестрам:

sequenceDiagram participant bank as Банк Получатель participant qb as Киви Банк qb->>bank:Реестр платежей bank->>qb:Ответный реестр qb-->>bank:Перечисление средств по подтвержденным платежам

Рекомендации по реализации протокола

Предпочтительны следующие варианты реализации Электронной цифровой подписи:

Возможны следующие варианты реализации канала связи:

Рекомендации по тестированию

При подключении обязательно проводится тестирование взаимодействия систем. Вам необходимо предоставить тестовые данные:

Обычно проводится следующий набор тестов:

Если для совершения операции используется несколько идентификаторов, например, номер счета и ФИО, то количество тестов увеличивается из-за комбинирования вариантов. Например, выполняются тесты с корректным номером счета и неправильным ФИО.

Часто задаваемые вопросы

Вопрос: Если мы получили запрос check со значениями sysno и sysid, которые уже приходили ранее в запросе check, мы должны выдать ошибку или выдать результат "прошлого check"?

Ответ: Ожидается результат "прошлого check".

Вопрос: Если мы получили запрос pay, для которого не было запроса check с теми же значениями sysno и sysid, мы должны выдать ошибку?

Ответ: Да, необходимо возвращать ошибку 171 (Check не найден или прошел с ошибкой).

Вопрос: Если мы получили запрос pay, должны ли мы проверять идентичность всех параметров этого запроса и ранее полученного запроса check с теми же значениями sysno и sysid?

Ответ: Нет, не должны. Опционально, можно проверить сумму.

Вопрос: Поле sysid — код платежной системы. Какая платежная система имеется в виду, и что это за код?

Ответ: Параметр sysid — это id процессинга внутри QIWI, из которого выполнен платеж. На стороне Контрагента sysid используется для проверки уникальности пары sysid + sysno.

Вопрос: В каких полях будут передаваться пользовательские идентификаторы?

Ответ: Номер договора — rec_agrno, Номер счета — rec_cre, Номер карты — rec_cardno

Вопрос: В чем смысл параметра mesid?

Ответ: При стандартной реализации значение будет всегда будет 3005 — финансовая транзакция для запросов check и pay. При согласовании нестандартной логики (например, возврат клиенту в интерфейс его ФИО или задолженности) могут использоваться другие значения.

Вопрос: Можете ли вы обрабатывать значение rec_name из нашего ответа на запрос check, в котором мы будет передавать ФИО владельца указанной карты/счёта, для проверки на вашей стороне и последующей передачи этого значения в соответствующем поле запроса pay?

Ответ: Да, можем. В этом случае будет использоваться следующая последовательность:

Вопрос: Какие поля обязательны для заполнения в наших ответных сообщениях на запросы check и pay?

Ответ: Следующие поля обязательны:

Примеры