NAV
XML

Введение

Последнее обновление: 2017-11-15 | Редактировать на GitHub

API выплат на кошельки предназначено для платежных агентов КИВИ Банк (АО), позволяет зачислять деньги на кошельки пользователей (балансы учетных записей клиентов в системе QIWI Wallet).

Что позволяет протокол

  1. Переводить деньги клиентам сервиса QIWI Кошелек - pay.
  2. Проверять существование клиентов в сервисе QIWI Кошелек - check-user.
  3. Следить за балансом на агентском счете для выплат - ping.

Как это работает

  1. Пользователь передает вам сумму пополнения и номер QIWI Кошелька, который нужно пополнить.
  2. Вы отправляете запрос в Top-Up API QIWI Кошелька на пополнение этого кошелька.
  3. Вы проверяете текущий статус платежа. Платеж должен принять финальный статус.
  4. При успешном финальном статусе платежа средства автоматически перечисляются на баланс кошелька пользователя с вашего агентского счета.
  5. При неуспешном финальном статусе платежа вы возвращаете средства пользователю.

По вопросам интеграции и сотрудничества пишите на bss@qiwi.com.

Формат взаимодействия

Взаимодействие происходит посредством пересылки запросов и ответов на них системы QIWI Wallet. Запросы и ответы – XML-документы в кодировке UTF-8.

Запросы отправляются по протоколу HTTPS на URL:

https://api.qiwi.com/xml/topup.jsp

Тип HTTP-запроса - POST, XML-документ помещается в теле HTTP-запроса. Формат значений тегов и атрибутов XML.

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

Аутентификация запросов выполняется по идентификатору и паролю, выдаваемому при подключении к системе QIWI Wallet. Смена пароля выполняется через сотрудников КИВИ Банк (АО) или сотрудников уполномоченного представителя КИВИ Банк (АО). Также возможна аутентификация по цифровой подписи или по клиентскому сертификату.

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

Единственным признаком, на основе которого вы можете принимать решение о успешности или неуспешности выполнения платежа на своей стороне, является статус транзакции в системе QIWI Wallet.

Каждому платежу (набору реквизитов: сумма, валюта, идентификатор клиента в системе QIWI Wallet, идентификатор сервиса) вы должны присваивать уникальный идентификатор.

Этапы процесса информационного взаимодействия при пополнении QIWI Кошелька отображены на диаграмме:

TopUp Sequence

Логическая последовательность операций при взаимодействии с системой QIWI Wallet должна соответствовать блок-схеме:

TopUp FlowChart

Аутентификация по SSL

Последнее обновление: 2017-07-11 | Редактировать на GitHub

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

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

Для аутентификации по цифровой подписи Контрагент должен создать пару RSA-ключей, например, с помощью утилиты OpenSSL. Размер ключа должен быть 2048 бит, ключ должен быть закодирован в BASE64.

Как создать ключи

openssl genrsa -out private.key 2048

Далее введите пароль и подтвердите:

Enter pass phrase for private.key:

В папке выполнения команды будет создан файл с приватным ключом: private.key.

openssl rsa -in private.key -pubout -out public.key

Как подписывать запросы

  1. Для каждого XML-пакета вычисляется хэш от текста XML-запроса с использованием выбранного алгоритма MD5 / SHA1, подписывается сохраненным закрытым ключом и кодируется по схеме Base64. Таким образом формируется ЭЦП пакета.
  2. В заголовке HTTP запроса передаются следующие параметры для выполнения авторизации и проверки целостности данных пакета:
    • X-Digital-Sign – ЭЦП пакета;
    • X-Digital-Sign-Alg – алгоритм вычисления ЭЦП, выбранный для вычисления хеша. Поддерживаются алгоритмы:
      • MD5withRSA
      • SHA1withRSA

Аутентификация по клиентскому сертификату

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

1. Создание CSR-запроса на сертификат

Запрос на сертификат генерируется одновременно с закрытым ключом, например, с помощью утилиты OpenSSL:

openssl req -new -nodes -batch -subj "/C=RU/ST=Russia/L=Moscow/O=QIWI/emailAddress=mail@qiwi.ru" -newkey rsa:2048 -keyout private.key -out cert_request.csr

В запросе Контрагент указывает свои данные: язык, страну, город, название организации и email. В примере запроса указаны данные QIWI.

В папке, в которой была выполнена команда, будет создан файл cert_request.csr и файл закрытого ключа private.key.

Далее формируется открытый ключ, соответствующий закрытому. Выполните команду:

openssl rsa -in private.key -pubout -out public.key

2. Получение сертификата

Открытый ключ и запрос на сертификат необходимо передать менеджеру QIWI. Менеджер возвращает Контрагенту СА-сертификат и клиентский сертификат, сформированный в ответ на запрос.

3. Отправка запросов

Запросы должны отправляться по адресу:

https://private-api.qiwi.com/xml/topup.jsp

Пополнение баланса

Последнее обновление: 2017-11-14 | Редактировать на GitHub

Операция используется для перевод средств с агентского счета на счет Клиента в системе QIWI Wallet.

Если Клиент с указанным идентификатором не существует в системе, то он будет создан в момент регистрации платежа.

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

При возникновении сетевых ошибок (например, таймауты при соединении или чтении ответа), HTTP-ошибок (HTTP-статус не равен 200, пустой ответ), некорректных XML-документов (например, c отсутствующими обязательными тегами и/или атрибутами) вы должны перейти к опросу статуса платежа до получения успешного или неуспешного финального статуса платежа. Поскольку при возникновении данных ошибок информация о статусе транзакции не доступна, вы не должны отклонять платеж на своей стороне.

Фатальность ошибки означает, что повторный запрос с теми же реквизитами приведет к повторению той же ошибки. Фатальные ошибки, как правило, вызваны ошибками конфигурирования и требуют ручного вмешательства (обращения в службу поддержки сервиса QIWI Кошелек).

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

Формат запроса

<?xml version="1.0" encoding="utf-8"?>
<request>
	<request-type>pay</request-type>
	<terminal-id>123</terminal-id>
	<extra name="password">***</extra>
	<auth>
		<payment>
			<transaction-number>12345678</transaction-number>
			<from>
				<ccy>RUB</ccy>
			</from>
			<to>
				<amount>15.00</amount>
				<ccy>RUB</ccy>
				<service-id>99</service-id>
				<account-number>79181234567</account-number>
			</to>
		</payment>
	</auth>
</request>

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

Тег Описание
request Группирующий тег. Дочерние теги содержат параметры платежа.
request-type Тип запроса (идентификатор запроса пополнения QIWI Кошелька: pay)
terminal-id Идентификатор агента в системе QIWI Wallet
extra name=”password” Экстра-поле, содержащее пароль для аутентификации в системе QIWI Wallet
auth Группирующий тег, описывает платежные данные
payment Группирующий тег, описывает единичный платеж. В запросе может присутствовать только один тег payment.
transaction-number Номер транзакции в информационной системе агента. Его необходимо использовать при проверке статуса платежа. Номер транзакции и идентификатор terminal-id однозначно определяют транзакцию в системе QIWI Wallet.
from Группирующий тег, содержит информацию о сумме, полученной агентом от клиента
ccy Валюта счета агента, с которого будет произведено списание денежных средств (в качестве значения используется цифровой или буквенный код валюты по ISO 4217)
service-id Идентификатор источника (канала) пополнения (необязательный параметр). Параметр используется в случае необходимости разделения потоков пополнения QIWI Кошельков, сохраняя единый баланс агента.
to Группирующий тег, содержит информацию о платеже
amount Сумма к зачислению на баланс учетной записи Клиента в системе QIWI Wallet. Система QIWI Wallet накладывает ограничения на сумму платежа, исходя из условий на остаток денежных средств учетной записи Клиента QIWI Wallet, указанных в оферте пользователя по адресу https://static.qiwi.com/ru/doc/oferta_lk.pdf. Платежи с суммой, менее разрешенной и более разрешенной, завершатся с ошибками 241 и 242 соответственно.
service-id Идентификатор сервиса (константа: 99)
account-number Идентификатор Клиента в системе QIWI Wallet (номер телефона Клиента системы QIWI Wallet в международном формате)
extra=”comment” Экстра-поле, содержащее комментарий (необязательный параметр)
ccy Валюта счета получателя, на который будут зачислены денежные средства (в качестве значения используется цифровой или буквенный код валюты по ISO 4217).

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

Ответ без ошибок обработки

<response>
<payment status='60' txn_id='6060' transaction-number='12345678' result-code='0' final-status='true' fatal-error='false' txn-date='02.03.2011 14:35:46'  >
  <from>
    <amount>15.00</amount>
    <ccy>643</ccy>
  </from>
  <to>
    <service-id>99</service-id>
    <amount>15.00</amount>
    <ccy>643</ccy>
    <account-number>79181234567</account-number>
  </to>
</payment>
<balances>
<balance code="428">0.00</balance>
<balance code="643">200</balance>
<balance code="840">12.20</balance>
</balances>
</response>

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

Тег Описание Атрибуты
response Группирующий тег ответа. Отсутствуют.
payment Описание принятого платежа. statusстатус платежа в системе QIWI Wallet;
    txn_id – идентификатор транзакции в системе QIWI Wallet;
    transaction-number – номер транзакции в информационной системе Контрагента;
    result-codeкод ошибки обработки платежа;
    final-status – флаг, определяющий финальность статуса платежа;
    fatal-error - флаг, определяющий фатальность ошибки обработки платежа;
    txn-date – дата приема платежа в систему QIWI Wallet;
from Группирующий тег, содержит информацию о списанных средствах. Отсутствуют.
amount Сумма, списанная со счета Контрагента. Отсутствуют.
ccy Валюта счета (в качестве значения используется цифровой или буквенный код валюты по ISO 4217). Отсутствуют.
to Группирующий тег, содержит информацию о платеже. Отсутствуют.
amount Сумма к зачислению на баланс учетной записи Клиента в системе QIWI Wallet. Отсутствуют.
service-id Идентификатор сервиса, на который производится зачисление средств (константа: 99). Отсутствуют.
account-number Идентификатор Клиента в системе QIWI Wallet. Отсутствуют.
ccy Валюта платежа (цифровой или буквенный код валюты по ISO 4217). Отсутствуют.
balances Группирующий тег, содержит информацию о балансе всех активных счетов Контрагента в системе QIWI Wallet. Отсутствуют.
balance Текущий баланс единичного счета Контрагента в системе QIWI Wallet code - цифровой код валюты счета (в формате ISO 4217).

Ответ с ошибками обработки

Если сервер не смог обработать запрос на пополнение баланса учетной записи Клиента в системе QIWI Wallet, он возвращает XML-ответ с описанием произошедшей ошибки.

<response>
  <result-code fatal="false">300</result-code>
</response>

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

Тег Описание Атрибуты
result-code Код ошибки обработки запроса. fatal – логический признак фатальности ошибки обработки запроса.

Проверка статуса платежа

Последнее обновление: 2017-11-14 | Редактировать на GitHub

Для проверки успешного прохождения платежа, Контрагент должен периодически выполнять запрос проверки статуса до получения успешного или неуспешного финального статуса.

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

Запрос позволяет получить текущий статус платежа. Повторный запрос для одних и тех же платежей следует отправлять не ранее, чем через 10 минут.

При появлении нефатальных ошибок запроса или нефинальных статусов платежей Контрагент должен делать повторный запрос проверки статуса платежа на сервер QIWI Wallet.

Фатальность ошибки обработки запроса означает, что повторный запрос с теми же параметрами приведет к повторению той же ошибки.

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

При возникновении сетевых ошибок (например, таймауты при соединении или чтении ответа), HTTP-ошибок (HTTP-статус не равен 200, пустой ответ), некорректных XML-документов (например, c отсутствующими тегами и/или атрибутами) Контрагент должен сделать повторный запрос. При возникновении данных ошибок информация о статусе транзакции не доступна, поэтому Контрагент не должен отклонять платеж на своей стороне.

Формат запроса

<?xml version="1.0" encoding="utf-8"?>
  <request>
    <request-type>pay</request-type>
    <extra name="password">XXXXXX</extra>
    <terminal-id>123</terminal-id>
    <status>
      <payment>
        <transaction-number>12345678</transaction-number>
        <to>
             <account-number>79181234567</account-number>
        </to>
      </payment>
    </status>
  </request>

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

Тег Описание
request Группирующий тег. Дочерние теги содержат параметры платежа.
request-type Тип запроса (равен идентификатору запроса пополнения QIWI Кошелька: pay)
terminal-id Идентификатор агента в системе QIWI Wallet
extra name=”password” Экстра-поле, содержащее пароль для аутентификации в системе QIWI Wallet
status Группирующий тег, содержит список платежей, по которым необходимо получить текущий статус. Данный тег заключает в своём теле один или более тегов payment
payment Группирующий тег, содержит данные единичного платежа, статус которого запрашивается.
transaction-number Номер транзакции в информационной системе Контрагента. Данный номер указывается при создании платежа. В сочетании с идентификатором Контрагента номер транзакции однозначно идентифицирует платеж в системе QIWI Wallet. Значение остается неизменным в течение всего срока существования платежа.
to Группирующий тег, содержит информацию о платеже
account-number Идентификатор Клиента в системе QIWI Wallet (номер телефона Клиента системы QIWI Wallet в международном формате)

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

Ответ без ошибок обработки запроса

<response>
  <result-code fatal="false">0</result-code>
  <payment status='60' transaction-number='12345678' txn_id='759640439' result-сode='0' final-status='true'  fatal-error='false' txn-date='12.03.2012 14:24:38'  />
  <balances>
    <balance code="643">90.79</balance>
    <balance code="840">0.00</balance>
  </balances>
</response>

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

Тег Описание Атрибуты
response Группирующий тег ответа. Отсутствуют.
payment Описание платежа, статус которого запрошен. В случае запроса статуса по нескольким платежам в ответе содержится соответствующее количество тегов payment. В случае, если запрашиваемый платеж не найден в системе QIWI Wallet, соответствующий тег payment будет отсутствовать в ответе. statusстатус платежа в системе QIWI Wallet;
    txn_id – идентификатор транзакции в системе QIWI Wallet;
    transaction-number – номер транзакции в информационной системе Контрагента;
    result-codeкод ошибки обработки платежа;
    final-status – флаг, определяющий финальность статуса платежа;
    fatal-error - флаг, определяющий фатальность ошибки обработки платежа;
    txn-date – дата приема платежа в систему QIWI Wallet;
balances Группирующий тег, содержит информацию о балансе всех активных счетов Контрагента в системе QIWI Wallet. Отсутствуют.
balance Текущий баланс единичного счета Контрагента в системе QIWI Wallet. code - цифровой код валюты счета (в формате ISO 4217).

Ответ с ошибками обработки запроса

Если сервер не смог обработать запрос на получение статуса платежа, он возвращает xml-ответ с описанием произошедшей ошибки.

<response>
  <result-code fatal="false">300</result-code>
</response>

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

Тег Описание Атрибуты
result-code Код ошибки обработки запроса. fatal – логический признак фатальности ошибки обработки запроса.

Проверка номера клиента

Последнее обновление: 2017-11-14 | Редактировать на GitHub

Данным запросом вы можете проверить, зарегистрирована ли учетная запись Клиента в системе QIWI Wallet, до проведения платежа.

Проверка существования учетной записи Клиента не является обязательной для регистрации платежа. При регистрации платежа отсутствующая в системе QIWI Wallet учетная запись Клиента создаётся автоматически.

Формат запроса

<?xml version="1.0" encoding="utf-8"?>
<request>
  <request-type>check-user</request-type>
  <terminal-id>123</terminal-id>
  <extra name="password">XXXXX</extra>
  <extra name="phone">79031234567</extra>
  <extra name="ccy">RUB</extra>
</request>

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

Тег Описание
request Группирующий тег
request-type Тип запроса (идентификатор запроса проверки существования учетной записи Клиента в системе: check-user)
terminal-id Идентификатор агента в системе QIWI Wallet
extra name=”password” Экстра-поле, содержащее пароль для аутентификации агента в системе QIWI Wallet
extra name=”phone” Экстра-поле, содержащее номер телефона Клиента, регистрацию учетной записи которого необходимо проверить
extra name=”ccy” Экстра-поле, содержащее код валюты учетной записи Клиента. Опциональный параметр. В случае его передачи проверяется наличие у Клиента учетной записи в данной валюте. В качестве значения используется цифровой или буквенный код валюты по ISO 4217.

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

<response>
  <result-code fatal="false">0</result-code>
  <exist>1</exist>
</response>

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

Тег Описание Атрибуты
result-code Код ошибки обработки запроса. fatal – логический признак фатальности ошибки обработки запроса.
exist Флаг, указывающий на существование учетной записи Клиента в системе QIWI Wallet. Флаг передается в ответе только в случае удачной обработки запроса (с кодом ошибки 0). Флаг может принимать значения:
0 – учетная запись Клиента не зарегистрирована в системе QIWI Wallet (в случае если в исходном запросе указана валюта (тег <extra name="ccy">), это означает, что у Клиента нет учетной записи в данной валюте);
1 – учетная запись Клиента зарегистрирована в системе QIWI Wallet (в случае если в исходном запросе указана валюта (тег <extra name="ccy">), это означает, что Клиент имеет учетную запись в данной валюте).
Отсутствуют.

Запрос баланса контрагента

Последнее обновление: 2017-11-14 | Редактировать на GitHub

Запрос ping возвращает текущий баланс по агентскому договору в сервисе QIWI Кошелек.

Формат запроса

<request>
<request-type>ping</request-type>
<terminal-id>44</terminal-id>
<extra name="password">password</extra>
</request>

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

Параметр Описание
request Группирующий тег
request-type Тип запроса (идентификатор запроса баланса: ping)
terminal-id Идентификатор агента в системе QIWI Wallet
extra name=”password” Экстра-поле, содержащее пароль для аутентификации в системе QIWI Wallet

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

<response>
<result-code fatal="false">0</result-code>
<balances>
  <balance code="428">100.00</balance>
  <balance code="643">200.26</balance>
  <balance code="840">300.00</balance>
</balances>
</response>

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

Параметр Описание Атрибуты
response Группирующий тег ответа. Отсутствуют.
result-code Код результата выполнения запроса. fatal - логический признак фатальности ошибки обработки платежа.
balances Группирующий тег, содержит информацию о балансе всех активных счетов Контрагента в системе QIWI Wallet. Отсутствуют.
balance Текущий баланс единичного счета Контрагента в системе QIWI Wallet. code - цифровой код валюты счета (в формате ISO 4217).

Статусы платежей

Последнее обновление: 2017-11-14 | Редактировать на GitHub

Сервер QIWI Wallet может возвращать статусы из следующих диапазонов:

Статус Описание Финальный статус
-1 Платеж не был зарегистрирован из-за временной ошибки. Попробуйте повторить запрос позже.  
0-49 Платеж принят, но ждет подтверждения со стороны системы QIWI Wallet. Свяжитесь с техническими специалистами системы QIWI Wallet: bss@qiwi.com -
50-59 Платеж находится в проведении. Средства списаны со счета Контрагента. -
50 Платеж принят в обработку -
52 Средства зачисляются на счет Клиента -
60 Платеж проведен +
> 100 Общий статус. Ошибка проведения платежа.Средства возвращены на баланс Контрагента. +
150 Платеж не принят +
151 Ошибка авторизации платежа +
160 Платеж не проведен или отменен +

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

Коды обработки

Код обработки Описание ошибки
0 Ошибок нет
155 Запрещен прием платежей в пользу данного сервиса (service-id в запросе проведения платежа должен быть равен 99)
215 Запрос проведения платежа содержит уже существующий номер транзакции платежа (transaction-number), но другие реквизиты платежа. Необходимо привести реквизиты платежа в соответствие данному номеру транзакции платежа.
220 Недостаточно средств на счете для проведения платежа
241 Сумма платежа меньше допустимой
242 Сумма платежа больше допустимой
298 Учетная запись Клиента с введенным номером телефона не может быть зарегистрирована в системе QIWI Wallet. Ошибочный номер телефона Клиента
300 Неизвестная ошибка обработки запроса. Обратитесь к техническим специалистам системы QIWI Wallet: bss@qiwi.com
316 Попытка авторизации заблокированного Контрагента
319 Запрет на пополнение учетной записи данного номера телефона
700 Превышен месячный лимит на операции
702 Превышен лимит на остаток учетной записи Клиента в системе QIWI Wallet

При появлении не описанных в данной таблице ошибок свяжитесь с техническими специалистами системы QIWI Wallet: bss@qiwi.com.

Коды ошибок

Код ошибки Описание Фатальность
0 Ошибок нет неприменимо
13 Повторите запрос через минуту -
150 Ошибка авторизации. Уточните логин и пароль, а затем повторите запрос +
300 Неизвестная ошибка. Повторите запрос -
339 Ограничение по IP адресу +

При появлении не описанных в данной таблице ошибок свяжитесь с техническими специалистами системы QIWI Wallet: bss@qiwi.com.

Формат XML-данных

Тег/атрибут Тип данных
request-type Строка буквенных символов
terminal-id Целое положительное число
transaction-number Целое положительное число до 20 разрядов
amount Дробное число (2 знака после запятой, разделителем является точка)
to/service-id Константа (99)
from/service-id Целое положительное число
account-number Номер телефона в международном формате без лидирующего знака +
final-status Логическое значение (true/false)
fatal-error Логическое значение (true/false)
txn-date Временная метка в следующем формате:
dd.MM.yyyy HH:mm:ss
balance Дробное число (2 знака после запятой, разделителем является точка)
fatal Логическое значение (true/false)
exist 0/1
"password" Строка символов
"comment" Строка символов (до 1000 символов)
"phone" Номер телефона в международном формате без лидирующего знака +
XML