Общие сведения

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

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

1. Выплачивать деньги на счета мобильных телефонов клиентам - pay.
2. Проверять принадлежность номера телефона мобильному оператору РФ - get-provider-by-phone-number.
3. Следить за балансом на агентском счете для выплат - ping.

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

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

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

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

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

Запросы отправляются по протоколу HTTPS на URL (если не указано иное):

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

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

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

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

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

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

Сценарий пополнения счета мобильного телефона отображен на диаграмме:

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

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

Редактировать на 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

• Контрагент должен передать открытый ключ в QIWI, а закрытый ключ использовать для подписи запросов.

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

POST /xml/topup.jsp HTTP/1.1
Content-Type: application/xml
Host: api.qiwi.com
X-Digital-Sign: XXXXXXXX
X-Digital-Sign-Alg: SHA1withRSA

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. Отправка запросов

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

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

Пример запроса с сертификатом:

user@pc:~/station$ openssl s_client -connect private-api.qiwi.com/xml/topup.jsp:443 -showcerts -CAfile ./CA/our_CA -cert ./my_cert -key ./private_key.pem

Выплаты на счета мобильных телефонов

Операция используется для выплаты средств на счета мобильных телефонов мобильных операторов РФ. Выплата средств в системе QIWI Wallet представляет собой списание средств с авансового депозита агента на баланс клиента системы QIWI Wallet и одновременное списание средств в пользу указанного мобильного оператора. При этом с клиента может взиматься комиссия в соответствии с тарифами, размещенными по адресу: https://qiwi.com/bank/rates

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

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

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

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

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

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

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

<?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>115.00</amount>
				<ccy>RUB</ccy>
				<service-id>29130</service-id>
				<account-number>7988111****</account-number>
				<extra name="account0">id:2;acc:988111****;sum:115.00</extra>
			</to>
		</payment>
	</auth>
</request>

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

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

<?xml version="1.0" encoding="utf-8"?>
<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>29130</service-id>
    <amount>115.00</amount>
    <ccy>643</ccy>
    <account-number>7988111****</account-number>
  </to>
</payment>
<balances>
<balance code="428">0.00</balance>
<balance code="643">200</balance>
<balance code="840">12.20</balance>
</balances>
</response>

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

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

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

<?xml version="1.0" encoding="utf-8"?>
<response>
  <result-code fatal="false">300</result-code>
</response>

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

Определение ID провайдера по номеру телефона

Данный запрос используется для определения ID провайдера мобильной связи по номеру телефона, т.е. определения принадлежности абонента.

Запросы должны отправляться на URL

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

При авторизации по сертификату запросы должны отправляться на URL

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

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

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

<?xml version="1.0" encoding="utf-8"?>
<request>
<request-type>get-provider-by-phone-number</request-type>
<terminal-id>***</terminal-id>
<phonenumber>916*******</phonenumber>
<extra name="password">***</extra>
</request>

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

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

<?xml version="1.0" encoding="utf-8"?>
<response>
<result-code fatal="false" message="Ок" msg="Ок">0</result-code>
<provider id="42"/>
</response>

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

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

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

<?xml version="1.0" encoding="utf-8"?>
<response>
  <result-code fatal="false">300</result-code>
</response>

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

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

Редактировать на GitHub

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

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

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

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

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

<?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>

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

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

Формат ответа зависит от того, как сервер обработал запрос:

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

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

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

Если запрос обработан корректно, то в ответе возвращаются сведения о статусе платежа в теге <payment>.

<?xml version="1.0" encoding="utf-8"?>
<response>
  <result-code fatal="false">0</result-code>
  <payment status='60' transaction-number='12345678' txn_id='759640439' result-сode='0' message='' msg='' 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>

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

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

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

<?xml version="1.0" encoding="utf-8"?>
<response>
  <result-code fatal="false" message="Неизвестная ошибка" msg="Неизвестная ошибка">300</result-code>
</response>

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

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

Редактировать на GitHub

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

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

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

<?xml version="1.0" encoding="utf-8"?>
<request>
<request-type>ping</request-type>
<terminal-id>44</terminal-id>
<extra name="password">password</extra>
</request>

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

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

Если запрос обработан корректно, то в ответе возвращаются сведения об агентском балансе.

<?xml version="1.0" encoding="utf-8"?>
<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>

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

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

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

<?xml version="1.0" encoding="utf-8"?>
<response>
  <result-code fatal="false" message="Неизвестная ошибка" msg="Неизвестная ошибка">300</result-code>
</response>

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

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

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

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

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

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

Коды ошибок

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

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