Как пользоваться API QIWI Мастера
Чтобы автоматически управлять картами в составе пакета QIWI Мастер, используйте API. С помощью API вы сможете:
Для настройки API и работы с ним вам потребуются базовые знания знание программирования на языках PHP или Python. Далее мы пошагово расскажем как отправлять запросы и обрабатывать ответы от сервиса QIWI. В примерах мы будем использовать язык программирования PHP. Для удобства скопируйте код к себе в рабочий файл.
Установка и настройка сервера
Пропустите этот шаг если вы знаете, как запустить сервер на локальном компьютере или на хостинге.
Для отправки запросов на API и обработки ответов вам нужно настроить сервер. Разберем, как установить сервер Apache и подготовить его к работе с API на локальном компьютере или арендовать сервер в интернете.
Сервер на персональном компьютере
После установки откройте контрольную панель XAMPP (появится ярлык на рабочем столе) и запустите сервер Apache.
Далее в папке C:\xampp\htdocs создайте папку своего проекта, например master-api. Размещайте в этой папке исполняемые файлы вашей программы.
В корне папки cоздайте файл index.php со следующим содержимым:
Аренда сервера у хостинг-компании
Этот способ быстрее, но нужен свободный домен, с которого будут отправляться запросы. Некоторые хостинг-провайдеры предоставляют домен в подарок при покупке хостинга. Желательно использовать SSL сертификат и отправлять запросы по https-протоколу. SSL сертификат нужен, чтобы ваш трафик не смогли расшифровать и подменить данные при отправке.
Для работы с API достаточно оплатить любой виртуальный хостинг с поддержкой скриптов на PHP и интерфейсом на cPanel (например тариф Host-A от Reg.ru). Виртуальные сервера VDS\VPS тоже подойдут, но на настройку понадобится больше времени.
После покупки хостинга откройте административную панель cPanel (доступы вам пришлют на почту).
Если вы купили хостинг с доменом — ничего настраивать не нужно. Переходите в менеджер файлов.
В корневой папке домена создайте файл index.php со следующим содержимым:
Подготовка к работе с API
Отправка запросов и обработка ответа
Любой запрос содержит заголовки и тело запроса. В заголовках передаётся тип запроса и авторизационный токен, а в теле — данные для отправки на сервер.
Покупка пакета QIWI мастер
Код запроса для покупки пакета QIWI Мастер:
В теле запроса нужно передать объект Payment и дополнительные обязательные поля:
Справа пример запроса на PHP, который выведет статус покупки пакета. Скопируйте этот код в файл index.php и перейдите в браузере на cтраницу:
После исполнения скрипта в браузере появится статус транзакции.
Покупка карты
Шаг 1. Создание заказа
Код запроса для создания заказа карты в составе пакета QIWI Мастер
Отправьте POST-запрос на адрес:
В ссылке запроса укажите номер кошелька с купленным пакетом QIWI Мастер. В теле запроса отправьте параметр cardAlias с возможными значениями:
В ответе на запрос придет номер заказа, который будет нужен для второго шага.
Шаг 2. Подтверждение заказа карты
Код для подтверждения заказа карты в составе пакета QIWI Мастер
Отправьте PUT-запрос на адрес:
https://edge.qiwi.com/cards/v2/persons/ /orders/ /submit
В ссылке запроса укажите номер кошелька с купленным пакетом QIWI Мастер и номер заказа из ответа в предыдущем шаге (поле id ). В теле запроса ничего не указывайте.
Успешный ответ на запрос будет содержать статус заказа.
Шаг 3. Покупка карты
Отправьте POST-запрос на адрес:
Список карт с реквизитами
Код для вывода номера карты, CVV и даты окончания обслуживания
Чтобы получить список карт, нужно отправить GET-запрос без параметров на адрес
Для получения реквизитов карт (PAN и CVV) нужен отдельный PUT-запрос на адрес
Введение
Последнее обновление: 2020-07-14 | Редактировать на GitHub
API выплат на кошельки предназначено для платежных агентов КИВИ Банк (АО), позволяет зачислять деньги на кошельки пользователей (балансы учетных записей клиентов в системе QIWI Wallet).
Что позволяет протокол
Как это работает
По вопросам интеграции и сотрудничества пишите на bss@qiwi.com.
Формат взаимодействия
Взаимодействие происходит посредством пересылки запросов и ответов на них системы QIWI Wallet. Запросы и ответы – XML-документы в кодировке UTF-8.
В API используются только HTTP POST-запросы, XML-документ помещается в теле HTTP-запроса. Используется только HTTPS-протокол.
Запросы в производственной среде отправляются по протоколу HTTPS на URL:
При использовании аутентификации по клиентскому сертификату запросы в производственной среде отправляются по протоколу HTTPS на URL:
Необходимо проверять подлинность сервера QIWI с помощью цепочки сертификации и не устанавливать соединение, если проверка не пройдет успешно.
Для повышения безопасности информационного обмена также может использоваться аутентификация по цифровой подписи или по клиентскому сертификату.
Единственным признаком, на основе которого вы можете принимать решение о успешности или неуспешности выполнения платежа на своей стороне, является статус транзакции в системе QIWI Wallet. Как только вы получили для вашего платежа идентификатор транзакции txn_id в системе QIWI Wallet, вы можете проверить статус транзакции методом Проверка статуса платежа.
Каждому платежу (набору реквизитов: сумма, валюта, идентификатор клиента в системе QIWI Wallet, идентификатор сервиса) вы должны присваивать уникальный идентификатор.
Этапы процесса информационного взаимодействия при пополнении QIWI Кошелька отображены на диаграмме:
Аутентификация по SSL
Последнее обновление: 2019-11-11 | Редактировать на GitHub
Помимо аутентификации по логину и паролю, может быть использована аутентификация по сертификатам, а также электронная цифровая подпись.
Аутентификация по цифровой подписи
Для аутентификации по цифровой подписи Контрагент должен создать пару RSA-ключей, например, с помощью утилиты OpenSSL. Размер ключа должен быть 2048 бит, ключ должен быть закодирован в BASE64.
Как создать ключи
Далее введите пароль и подтвердите:
Enter pass phrase for private.key:
Как подписывать запросы
Аутентификация по клиентскому сертификату
Для аутентификации по клиентскому сертификату Контрагенту необходимо создать, а затем передать запрос на сертификат и открытый ключ в QIWI.
1. Создание CSR-запроса на сертификат
Запрос на сертификат генерируется одновременно с закрытым ключом, например, с помощью утилиты OpenSSL:
В запросе Контрагент указывает свои данные: язык, страну, город, название организации и email. В примере запроса указаны данные QIWI.
Далее формируется открытый ключ, соответствующий закрытому. Выполните команду:
2. Получение сертификата
Открытый ключ и запрос на сертификат необходимо передать менеджеру QIWI. Менеджер возвращает Контрагенту СА-сертификат и клиентский сертификат, сформированный в ответ на запрос.
3. Отправка запросов
Запросы к API должны отправляться по адресу:
Пример запроса с сертификатом:
Пополнение баланса QIWI Кошелька
Последнее обновление: 2020-07-10 | Редактировать на GitHub
Запрос используется для перевода средств с агентского счета на счет клиента в системе QIWI Wallet.
Если клиент с указанным номером кошелька не существует в системе QIWI Wallet и проведение платежа возможно, то клиент будет создан в момент регистрации платежа.
После успешного выполнения запроса платеж начинает жизненный цикл в системе QIWI Wallet. Каждому этапу жизненного цикла соответствует свой статус платежа. Если в ответе на запрос выплаты получен нефинальный статус платежа, то для проверки успешного прохождения платежа вы должны периодически (но не чаще одного раза в 10 минут) выполнять запрос проверки статуса платежа до получения успешного или неуспешного финального статуса платежа. Коды финальных статусов указаны в списке возвращаемых API статусов платежа.
Формат запроса
Параметры запроса
Формат ответа
При возникновении сетевых ошибок (например, таймауты при соединении или чтении ответа), HTTP-ошибок (HTTP-статус не равен 200, пустой ответ), некорректных XML-документов (например, c отсутствующими обязательными тегами и/или атрибутами) вы должны перейти к опросу статуса платежа до получения успешного или неуспешного финального статуса платежа. Поскольку в таких случаях информация о статусе транзакции не доступна, вы не должны отклонять платеж на своей стороне.
Формат ответа API зависит от того, как сервер обработал запрос:
Ответ без ошибок обработки запроса
Если запрос обработан корректно, то в ответе возвращаются сведения о платеже в теге
Ответ с ошибками обработки запроса
Если сервер не смог обработать запрос на пополнение баланса учетной записи Клиента в системе QIWI Wallet, API возвращает ответ с кодом произошедшей ошибки. В этом случае информация о транзакции отсутствует в ответе, поэтому вы должны перейти к запросам статуса, не отклоняя платеж на своей стороне.
Проверка статуса платежа
Последнее обновление: 2017-11-14 | Редактировать на GitHub
С момента регистрации платеж проходит стадии жизненного цикла, изменяющие его статус. Каждый статус задается уникальным числовым идентификатором.
Проведение платежа считается завершенным, когда он достигает финального статуса. Значения статусов с указанием признака финальности приведены в разделе Статусы платежей.
Для проверки успешного прохождения платежа, вы должны периодически выполнять данный запрос до получения успешного или неуспешного финального статуса. Запрос позволяет получить текущий статус платежа.
Формат запроса
Параметры запроса
| Тег | Описание |
|---|---|
| request | Группирующий тег. Дочерние теги содержат параметры платежа. |
| request-type | Тип запроса (равен идентификатору запроса пополнения QIWI Кошелька: pay ) |
| terminal-id | Идентификатор агента в системе QIWI Wallet |
| extra name=»password» | Экстра-поле, содержащее пароль для аутентификации в системе QIWI Wallet |
| status | Группирующий тег, содержит список платежей, по которым необходимо получить текущий статус. Данный тег может содержать один или более тегов payment |
| payment | Группирующий тег, содержит данные единичного платежа, статус которого запрашивается. |
| transaction-number | Номер транзакции платежа в информационной системе Контрагента. Должен совпадать с номером, указанным при создании этого платежа. В сочетании с идентификатором Контрагента номер транзакции однозначно идентифицирует платеж в системе QIWI Wallet. Значение остается неизменным в течение жизненного цикла платежа. |
| to | Группирующий тег, содержит информацию о платеже |
| to/account-number | Идентификатор Клиента в системе QIWI Wallet (номер телефона Клиента системы QIWI Wallet в международном формате) |
Формат ответа
При возникновении сетевых ошибок (например, таймауты при соединении или чтении ответа), HTTP-ошибок (HTTP-статус не равен 200, пустой ответ), некорректных XML-документов (например, c отсутствующими тегами и/или атрибутами) вы должны сделать повторный запрос. В таких случаях информация о статусе транзакции не доступна, поэтому вы не должны отклонять платеж на своей стороне.
Формат ответа зависит от того, как сервер обработал запрос:
При возврате ответов с ошибками запроса или с нефинальными статусами платежей вы должны сделать повторный запрос проверки статуса платежа.
Ответ без ошибок обработки запроса
Если запрос обработан корректно, то в ответе возвращаются сведения о статусе платежа в теге
Ответ с ошибками обработки запроса
Если сервер не смог обработать запрос на получение статуса платежа, API возвращает ответ с кодом произошедшей ошибки. В этом случае информация о статусе транзакции отсутствует в ответе, поэтому вы должны продолжать запросы статуса, не отклоняя платеж на своей стороне.
Проверка возможности проведения платежа
Последнее обновление: 2020-07-14 | Редактировать на GitHub
Данным запросом вы должны проверить, возможно ли проведение платежа для пополнения учетной записи клиента в системе QIWI Wallet.
Если вам необходима только проверка регистрации учетной записи, то используйте этот запрос.
Формат запроса
Параметры запроса
| Тег | Описание |
|---|---|
| request | Группирующий тег |
| request-type | Тип запроса (идентификатор запроса проверки возможности проведения платежа: check-deposit-possible ). |
| terminal-id | Идентификатор агента в системе QIWI Wallet. |
| extra name=»password» | Экстра-поле, содержащее пароль для аутентификации агента в системе QIWI Wallet. |
| extra name=»phone» | Экстра-поле, содержащее номер телефона клиента. |
| extra name=»income_wire_transfer» | Экстра-поле, содержащее целочисленный признак безналичных (1) или наличных (0) средств, полученных от клиента для пополнения его учетной записи в системе QIWI Wallet. |
| extra name=»ccy» | Экстра-поле, содержащее код валюты учетной записи клиента. Опциональный параметр. В случае его передачи проверяется возможность проведения платежа для пополнения учетной записи в данной валюте. В качестве значения используется цифровой или буквенный код валюты по ISO 4217. |
Формат ответа
Ответ без ошибок обработки запроса
Если запрос обработан корректно, то в ответе возвращаются сведения о возможности проведения платежа.
| Тег | Описание | Атрибуты |
|---|---|---|
| result-code | Код ошибки обработки запроса. | fatal – логический признак фатальности ошибки обработки запроса. |
| exist | Целочисленный флаг, указывающий на существование учетной записи клиента в системе QIWI Wallet. Флаг передается в ответе только в случае удачной обработки запроса (с кодом ошибки 0). Флаг может принимать значения: 0 – учетная запись клиента не зарегистрирована в системе QIWI Wallet (в случае если в исходном запросе указана валюта (тег ), это означает, что у клиента нет учетной записи в данной валюте); 1 – учетная запись клиента зарегистрирована в системе QIWI Wallet (в случае если в исходном запросе указана валюта (тег ), это означает, что клиент имеет учетную запись в данной валюте). | Отсутствуют. |
| deposit-possible | Целочисленный флаг, указывающий на возможность пополнения учетной записи клиента в системе QIWI Wallet. Флаг передается в ответе только в случае удачной обработки запроса (с кодом ошибки 0). Флаг может принимать значения: 0 – учетную запись клиента нельзя пополнить указанным в запросе типом средств. Платеж будет отклонён. 1 – учетную запись клиента можно пополнить указанным в запросе типом средств. | Отсутствуют. |
Ответ с ошибками обработки запроса
Если сервер не смог обработать запрос, API возвращает ответ с кодом произошедшей ошибки.
Проверка регистрации клиента
Последнее обновление: 2017-11-14 | Редактировать на GitHub
Данным запросом вы можете до проведения платежа проверить, зарегистрирована ли учетная запись Клиента в системе QIWI Wallet.
Проверка существования учетной записи Клиента не является обязательной для регистрации платежа. При успешной регистрации платежа отсутствующая в системе QIWI Wallet учетная запись Клиента создаётся автоматически.
Формат запроса
Параметры запроса
| Тег | Описание |
|---|---|
| request | Группирующий тег |
| request-type | Тип запроса (идентификатор запроса проверки существования учетной записи Клиента в системе: check-user ) |
| terminal-id | Идентификатор агента в системе QIWI Wallet |
| extra name=»password» | Экстра-поле, содержащее пароль для аутентификации агента в системе QIWI Wallet |
| extra name=»phone» | Экстра-поле, содержащее номер телефона Клиента, регистрацию учетной записи которого необходимо проверить |
| extra name=»ccy» | Экстра-поле, содержащее код валюты учетной записи Клиента. Опциональный параметр. В случае его передачи проверяется наличие у Клиента учетной записи в данной валюте. В качестве значения используется цифровой или буквенный код валюты по ISO 4217. |
Формат ответа
Ответ без ошибок обработки запроса
Если запрос обработан корректно, то в ответе возвращаются сведения о Клиенте.
| Тег | Описание | Атрибуты |
|---|---|---|
| result-code | Код ошибки обработки запроса. | fatal – логический признак фатальности ошибки обработки запроса. |
| exist | Флаг, указывающий на существование учетной записи Клиента в системе QIWI Wallet. Флаг передается в ответе только в случае удачной обработки запроса (с кодом ошибки 0). Флаг может принимать значения: 0 – учетная запись Клиента не зарегистрирована в системе QIWI Wallet (в случае если в исходном запросе указана валюта (тег ), это означает, что у Клиента нет учетной записи в данной валюте); 1 – учетная запись Клиента зарегистрирована в системе QIWI Wallet (в случае если в исходном запросе указана валюта (тег ), это означает, что Клиент имеет учетную запись в данной валюте). | Отсутствуют. |
Ответ с ошибками обработки запроса
Если сервер не смог обработать запрос, API возвращает ответ с кодом произошедшей ошибки.
Запрос баланса контрагента
Последнее обновление: 2017-11-14 | Редактировать на GitHub
Данный запрос возвращает текущий баланс по агентскому договору в сервисе QIWI Кошелек.
Формат запроса
Параметры запроса
| Параметр | Описание |
|---|---|
| request | Группирующий тег |
| request-type | Тип запроса (идентификатор запроса баланса: ping ) |
| terminal-id | Идентификатор агента в системе QIWI Wallet |
| extra name=»password» | Экстра-поле, содержащее пароль для аутентификации в системе QIWI Wallet |
Формат ответа
Ответ без ошибок обработки запроса
Если запрос обработан корректно, то в ответе возвращаются сведения об агентском балансе.
Ответ с ошибками обработки запроса
Если сервер не смог обработать запрос, API возвращает ответ с кодом произошедшей ошибки.
Статусы платежей
Последнее обновление: 2020-07-10 | Редактировать на GitHub
Для платежных запросов (пополнение кошелька, проверка статуса платежа) API возвращает статус платежа в атрибуте status тега
Финальный статус означает, что жизненный цикл платежа в сервисе QIWI Wallet завершен и его статус больше не изменится.
API возвращает статусы из следующих диапазонов:
Коды ошибок обработки платежа
Для платежных запросов (пополнение кошелька, проверка статуса платежа) API возвращает информационный код ошибки обработки платежа в атрибуте result-code тега
| Код ошибки | Описание ошибки |
|---|---|
| 0 | Ошибок нет |
| 155 | Запрещен прием платежей в пользу данного сервиса (тег to/service-id в запросе проведения платежа должен быть равен 99 ) |
| 204 | Недостаточный статус идентификации кошелька для проведения платежа |
| 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.
Коды ошибок обработки запроса
Данные коды возвращаются в теге ответа API. Ошибки с кодом > 0 возвращаются, если сервер не смог обработать запрос (в ответе отсутствуют запрашиваемые данные).
Введение
Последнее обновление: 2020-07-14
API выплат на карты и QIWI Кошельки предназначено для платежных агентов КИВИ Банк (АО), позволяет зачислять деньги на банковские карты клиентов, выпущенные платежными системами VISA, MasterCard, МИР, а также на кошельки пользователей (балансы учетных записей клиентов в системе QIWI Wallet).
Что позволяет протокол
Как это работает
Выплаты на банковские карты
Выплаты на QIWI Кошельки
Обратная связь
По вопросам интеграции и сотрудничества пишите на bss@qiwi.com.
Формат взаимодействия
Взаимодействие происходит посредством пересылки запросов и ответов на них системы QIWI Wallet. Запросы и ответы – XML-документы в кодировке UTF-8.
В API используются только HTTP POST-запросы, XML-документ помещается в теле HTTP-запроса. Используется только HTTPS-протокол.
Запросы в производственной среде отправляются по протоколу HTTPS на URL:
При авторизации по клиентскому сертификату запросы в производственной среде отправляются по протоколу HTTPS на URL:
Необходимо проверять подлинность сервера QIWI с помощью цепочки сертификации и не устанавливать соединение, если проверка не пройдет успешно.
Для повышения безопасности информационного обмена также может использоваться аутентификация по цифровой подписи или по клиентскому сертификату.
Единственным признаком, на основе которого вы можете принимать решение о успешности или неуспешности выполнения платежа на своей стороне, является статус транзакции в системе QIWI Wallet. Как только вы получили для вашего платежа идентификатор транзакции txn_id в системе QIWI Wallet, вы можете проверить статус транзакции методом Проверка статуса платежа.
Каждому платежу (набору реквизитов: сумма, валюта, идентификатор сервиса) вы должны присваивать уникальный идентификатор.
Этапы процесса информационного взаимодействия при выплате на карту
Этапы процесса информационного взаимодействия при пополнении QIWI Кошелька
Аутентификация по SSL
Последнее обновление: 2019-11-11 | Редактировать на GitHub
Помимо аутентификации по логину и паролю, может быть использована аутентификация по сертификатам, а также электронная цифровая подпись.
Аутентификация по цифровой подписи
Для аутентификации по цифровой подписи Контрагент должен создать пару RSA-ключей, например, с помощью утилиты OpenSSL. Размер ключа должен быть 2048 бит, ключ должен быть закодирован в BASE64.
Как создать ключи
Далее введите пароль и подтвердите:
Enter pass phrase for private.key:
Как подписывать запросы
Аутентификация по клиентскому сертификату
Для аутентификации по клиентскому сертификату Контрагенту необходимо создать, а затем передать запрос на сертификат и открытый ключ в QIWI.
1. Создание CSR-запроса на сертификат
Запрос на сертификат генерируется одновременно с закрытым ключом, например, с помощью утилиты OpenSSL:
В запросе Контрагент указывает свои данные: язык, страну, город, название организации и email. В примере запроса указаны данные QIWI.
Далее формируется открытый ключ, соответствующий закрытому. Выполните команду:
2. Получение сертификата
Открытый ключ и запрос на сертификат необходимо передать менеджеру QIWI. Менеджер возвращает Контрагенту СА-сертификат и клиентский сертификат, сформированный в ответ на запрос.
3. Отправка запросов
Запросы к API должны отправляться по адресу:
Пример запроса с сертификатом:
Выплаты на карты банков РФ
Последнее обновление: 2018-11-01
Операция используется для выплаты средств на банковские карты платежных систем. Выплата средств в системе QIWI Wallet представляет собой списание средств с авансового депозита агента и зачисление на банковские карты международных платежных систем «Visa International», «MasterCard International Incorporated», платежной системы «Мир», эмитированные кредитными организациями РФ. Платежная система определяется по номеру карты.
После выполнения запроса платеж начинает свой жизненный цикл в системе QIWI Wallet. Каждому этапу жизненного цикла соответствует свой статус платежа. Если в ответе на запрос выплаты получен нефинальный статус платежа, то для проверки успешного прохождения платежа вы должны периодически (но не чаще одного раза в 10 минут) выполнять запрос проверки статуса платежа до получения успешного или неуспешного финального статуса платежа. Коды финальных статусов указаны в списке возвращаемых API статусов платежа.
Формат запроса
Параметры запроса
Формат ответа
При возникновении сетевых ошибок (например, таймауты при соединении или чтении ответа), HTTP-ошибок (HTTP-статус не равен 200, пустой ответ), некорректных XML-документов (например, c отсутствующими обязательными тегами и/или атрибутами) вы должны перейти к опросу статуса платежа до получения успешного или неуспешного финального статуса платежа. Поскольку при возникновении данных ошибок информация о статусе транзакции не доступна, вы не должны отклонять платеж на своей стороне.
Формат ответа API зависит от того, как сервер обработал запрос:
Ответ без ошибок обработки
Если запрос обработан корректно, то в ответе возвращаются сведения о платеже в теге
Ответ с ошибками обработки
Если сервер не смог обработать запрос на пополнение карты, API возвращает ответ с кодом произошедшей ошибки. В этом случае информация о транзакции отсутствует в ответе, поэтому вы должны перейти к запросам статуса, не отклоняя платеж на своей стороне.
Выплаты на карты зарубежных банков
Последнее обновление: 2020-10-08
Операция используется для выплаты средств на банковские карты, выпущенные зарубежными банками. Выплата средств в системе QIWI Wallet представляет собой списание средств с авансового депозита агента и зачисление на банковские карты международных платежных систем «Visa International», «MasterCard International Incorporated», эмитированные зарубежными кредитными организациями. Платежная система определяется по номеру карты.
После выполнения запроса платеж начинает свой жизненный цикл в системе QIWI Wallet. Каждому этапу жизненного цикла соответствует свой статус платежа. Если в ответе на запрос выплаты получен нефинальный статус платежа, то для проверки успешного прохождения платежа вы должны периодически (но не чаще одного раза в 10 минут) выполнять запрос проверки статуса платежа до получения успешного или неуспешного финального статуса платежа. Коды финальных статусов указаны в списке возвращаемых API статусов платежа.
Формат запроса
Параметры запроса
Внутри тега payment поля с тегом extra могут располагаться в любом порядке
Формат ответа
При возникновении сетевых ошибок (например, таймауты при соединении или чтении ответа), HTTP-ошибок (HTTP-статус не равен 200, пустой ответ), некорректных XML-документов (например, c отсутствующими обязательными тегами и/или атрибутами) вы должны перейти к опросу статуса платежа до получения успешного или неуспешного финального статуса платежа. Поскольку при возникновении данных ошибок информация о статусе транзакции не доступна, вы не должны отклонять платеж на своей стороне.
Формат ответа API зависит от того, как сервер обработал запрос:
Ответ без ошибок обработки
Если запрос обработан корректно, то в ответе возвращаются сведения о платеже в теге
Ответ с ошибками обработки
Если сервер не смог обработать запрос на пополнение карты, API возвращает ответ с кодом произошедшей ошибки. В этом случае информация о транзакции отсутствует в ответе, поэтому вы должны перейти к запросам статуса, не отклоняя платеж на своей стороне.
Пополнение баланса QIWI Кошелька
Последнее обновление: 2020-07-10 | Редактировать на GitHub
Запрос используется для перевода средств с агентского счета на счет клиента в системе QIWI Wallet.
Если клиент с указанным номером кошелька не существует в системе QIWI Wallet и проведение платежа возможно, то клиент будет создан в момент регистрации платежа.
После успешного выполнения запроса платеж начинает жизненный цикл в системе QIWI Wallet. Каждому этапу жизненного цикла соответствует свой статус платежа. Если в ответе на запрос выплаты получен нефинальный статус платежа, то для проверки успешного прохождения платежа вы должны периодически (но не чаще одного раза в 10 минут) выполнять запрос проверки статуса платежа до получения успешного или неуспешного финального статуса платежа. Коды финальных статусов указаны в списке возвращаемых API статусов платежа.
Формат запроса
Параметры запроса
Формат ответа
При возникновении сетевых ошибок (например, таймауты при соединении или чтении ответа), HTTP-ошибок (HTTP-статус не равен 200, пустой ответ), некорректных XML-документов (например, c отсутствующими обязательными тегами и/или атрибутами) вы должны перейти к опросу статуса платежа до получения успешного или неуспешного финального статуса платежа. Поскольку в таких случаях информация о статусе транзакции не доступна, вы не должны отклонять платеж на своей стороне.
Формат ответа API зависит от того, как сервер обработал запрос:
Ответ без ошибок обработки запроса
Если запрос обработан корректно, то в ответе возвращаются сведения о платеже в теге
Ответ с ошибками обработки запроса
Если сервер не смог обработать запрос на пополнение баланса учетной записи Клиента в системе QIWI Wallet, API возвращает ответ с кодом произошедшей ошибки. В этом случае информация о транзакции отсутствует в ответе, поэтому вы должны перейти к запросам статуса, не отклоняя платеж на своей стороне.
Проверка статуса платежа
Последнее обновление: 2017-11-14 | Редактировать на GitHub
С момента регистрации платеж проходит стадии жизненного цикла, изменяющие его статус. Каждый статус задается уникальным числовым идентификатором.
Проведение платежа считается завершенным, когда он достигает финального статуса. Значения статусов с указанием признака финальности приведены в разделе Статусы платежей.
Для проверки успешного прохождения платежа, вы должны периодически выполнять данный запрос до получения успешного или неуспешного финального статуса. Запрос позволяет получить текущий статус платежа.
Формат запроса
Параметры запроса
| Тег | Описание |
|---|---|
| request | Группирующий тег. Дочерние теги содержат параметры платежа. |
| request-type | Тип запроса (равен идентификатору запроса пополнения QIWI Кошелька: pay ) |
| terminal-id | Идентификатор агента в системе QIWI Wallet |
| extra name=»password» | Экстра-поле, содержащее пароль для аутентификации в системе QIWI Wallet |
| status | Группирующий тег, содержит список платежей, по которым необходимо получить текущий статус. Данный тег может содержать один или более тегов payment |
| payment | Группирующий тег, содержит данные единичного платежа, статус которого запрашивается. |
| transaction-number | Номер транзакции платежа в информационной системе Контрагента. Должен совпадать с номером, указанным при создании этого платежа. В сочетании с идентификатором Контрагента номер транзакции однозначно идентифицирует платеж в системе QIWI Wallet. Значение остается неизменным в течение жизненного цикла платежа. |
| to | Группирующий тег, содержит информацию о платеже |
| to/account-number | Идентификатор Клиента в системе QIWI Wallet (номер телефона Клиента системы QIWI Wallet в международном формате) |
Формат ответа
При возникновении сетевых ошибок (например, таймауты при соединении или чтении ответа), HTTP-ошибок (HTTP-статус не равен 200, пустой ответ), некорректных XML-документов (например, c отсутствующими тегами и/или атрибутами) вы должны сделать повторный запрос. В таких случаях информация о статусе транзакции не доступна, поэтому вы не должны отклонять платеж на своей стороне.
Формат ответа зависит от того, как сервер обработал запрос:
При возврате ответов с ошибками запроса или с нефинальными статусами платежей вы должны сделать повторный запрос проверки статуса платежа.
Ответ без ошибок обработки запроса
Если запрос обработан корректно, то в ответе возвращаются сведения о статусе платежа в теге
Ответ с ошибками обработки запроса
Если сервер не смог обработать запрос на получение статуса платежа, API возвращает ответ с кодом произошедшей ошибки. В этом случае информация о статусе транзакции отсутствует в ответе, поэтому вы должны продолжать запросы статуса, не отклоняя платеж на своей стороне.
Проверка возможности проведения платежа
Последнее обновление: 2020-07-14 | Редактировать на GitHub
Данным запросом вы должны проверить, возможно ли проведение платежа для пополнения учетной записи клиента в системе QIWI Wallet.
Если вам необходима только проверка регистрации учетной записи, то используйте этот запрос.
Формат запроса
Параметры запроса
| Тег | Описание |
|---|---|
| request | Группирующий тег |
| request-type | Тип запроса (идентификатор запроса проверки возможности проведения платежа: check-deposit-possible ). |
| terminal-id | Идентификатор агента в системе QIWI Wallet. |
| extra name=»password» | Экстра-поле, содержащее пароль для аутентификации агента в системе QIWI Wallet. |
| extra name=»phone» | Экстра-поле, содержащее номер телефона клиента. |
| extra name=»income_wire_transfer» | Экстра-поле, содержащее целочисленный признак безналичных (1) или наличных (0) средств, полученных от клиента для пополнения его учетной записи в системе QIWI Wallet. |
| extra name=»ccy» | Экстра-поле, содержащее код валюты учетной записи клиента. Опциональный параметр. В случае его передачи проверяется возможность проведения платежа для пополнения учетной записи в данной валюте. В качестве значения используется цифровой или буквенный код валюты по ISO 4217. |
Формат ответа
Ответ без ошибок обработки запроса
Если запрос обработан корректно, то в ответе возвращаются сведения о возможности проведения платежа.
| Тег | Описание | Атрибуты |
|---|---|---|
| result-code | Код ошибки обработки запроса. | fatal – логический признак фатальности ошибки обработки запроса. |
| exist | Целочисленный флаг, указывающий на существование учетной записи клиента в системе QIWI Wallet. Флаг передается в ответе только в случае удачной обработки запроса (с кодом ошибки 0). Флаг может принимать значения: 0 – учетная запись клиента не зарегистрирована в системе QIWI Wallet (в случае если в исходном запросе указана валюта (тег ), это означает, что у клиента нет учетной записи в данной валюте); 1 – учетная запись клиента зарегистрирована в системе QIWI Wallet (в случае если в исходном запросе указана валюта (тег ), это означает, что клиент имеет учетную запись в данной валюте). | Отсутствуют. |
| deposit-possible | Целочисленный флаг, указывающий на возможность пополнения учетной записи клиента в системе QIWI Wallet. Флаг передается в ответе только в случае удачной обработки запроса (с кодом ошибки 0). Флаг может принимать значения: 0 – учетную запись клиента нельзя пополнить указанным в запросе типом средств. Платеж будет отклонён. 1 – учетную запись клиента можно пополнить указанным в запросе типом средств. | Отсутствуют. |
Ответ с ошибками обработки запроса
Если сервер не смог обработать запрос, API возвращает ответ с кодом произошедшей ошибки.
Запрос баланса контрагента
Последнее обновление: 2017-11-14 | Редактировать на GitHub
Данный запрос возвращает текущий баланс по агентскому договору в сервисе QIWI Кошелек.
Формат запроса
Параметры запроса
| Параметр | Описание |
|---|---|
| request | Группирующий тег |
| request-type | Тип запроса (идентификатор запроса баланса: ping ) |
| terminal-id | Идентификатор агента в системе QIWI Wallet |
| extra name=»password» | Экстра-поле, содержащее пароль для аутентификации в системе QIWI Wallet |
Формат ответа
Ответ без ошибок обработки запроса
Если запрос обработан корректно, то в ответе возвращаются сведения об агентском балансе.
Ответ с ошибками обработки запроса
Если сервер не смог обработать запрос, API возвращает ответ с кодом произошедшей ошибки.
Статусы платежей
Последнее обновление: 2020-07-10
Для платежных запросов (пополнение карты, пополнение кошелька, проверка статуса платежа) API возвращает статус платежа в атрибуте status тега
Финальный статус означает, что жизненный цикл платежа в сервисе QIWI Wallet завершен и его статус больше не изменится.
API возвращает статусы из следующих диапазонов:
Коды ошибок обработки платежа
Для платежных запросов (пополнение карты, пополнение кошелька, проверка статуса платежа) API возвращает информационный код ошибки обработки платежа в атрибуте result-code тега
| Код обработки | Описание ошибки |
|---|---|
| 0 | Ошибок нет |
| 155 | Запрещен прием платежей в пользу данного сервиса (тег to/service-id в запросе проведения платежа должен быть равен 34020 для выплат на карты или 99 для пополнений QIWI Кошелька) |
| 204 | Недостаточный статус идентификации кошелька для проведения платежа пополнения кошелька |
| 215 | Запрос проведения платежа содержит уже существующий номер транзакции платежа ( transaction-number ), но другие реквизиты платежа. Необходимо привести реквизиты платежа в соответствие данному номеру транзакции платежа. |
| 220 | Недостаточно средств на счете для проведения платежа |
| 242 | Сумма платежа больше допустимой |
| 300 | Неизвестная ошибка обработки запроса. Обратитесь к техническим специалистам системы QIWI Wallet: bss@qiwi.com |
| 316 | Попытка авторизации заблокированного Контрагента |
При появлении не описанных в данной таблице ошибок свяжитесь с техническими специалистами системы QIWI Wallet: bss@qiwi.com.
Коды ошибок обработки запроса
Данные коды возвращаются в теге ответа API. Ошибки с кодом > 0 возвращаются, если сервер не смог обработать запрос (в ответе отсутствуют запрашиваемые данные).
