что такое api ключ qiwi

Введение

Последнее обновление: 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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Если вам необходима только проверка регистрации учетной записи, то используйте этот запрос.

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

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

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

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

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

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

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

Проверка регистрации клиента

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Для платежных запросов (пополнение кошелька, проверка статуса платежа) API возвращает статус платежа в атрибуте status тега

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

API возвращает статусы из следующих диапазонов:

Коды ошибок обработки платежа

Для платежных запросов (пополнение кошелька, проверка статуса платежа) API возвращает информационный код ошибки обработки платежа в атрибуте result-code тега

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

Коды ошибок обработки запроса

Данные коды возвращаются в теге ответа API. Ошибки с кодом > 0 возвращаются, если сервер не смог обработать запрос (в ответе отсутствуют запрашиваемые данные).

Источник

Инструкция по работе с API QIWI Мастер

Чтобы автоматически управлять картами в составе пакета QIWI Мастер вы можете воспользоваться специальным API. С помощью API вы сможете:

Для настройки API и работы с ним вам потребуются базовые знания знание программирования на языках PHP или Python. Далее мы пошагово расскажем как отправлять запросы и обрабатывать ответы от сервиса QIWI.

Попробуйте интерфейс для управления вирутальными картами QIWI Мастер по API.

Установка и настройка сервера

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

Для отправки запросов через API и обработки ответов вам нужно настроить сервер. Разберем, как установить сервер Apache на домашнем компьютере или арендовать сервер в интернете. В примерах мы будем использовать язык программирования PHP.

Сервер на домашнем компьютере

В этой папке будут лежать исполняемые файлы вашей программы.

Аренда сервера у хостинг-компании

Этот способ быстрее, но нужен свободный домен, с которого будут отправляться запросы. Некоторые хостинг-провайдеры предоставляют домен в подарок при покупке хостинга. Желательно использовать ssl сертификат и отправлять запросы по https-протоколу. SSL сертификат нужен, чтобы ваш трафик не смогли расшифровать и подменить данные при отправке.

Для работы с API достаточно оплатить любой виртуальный хостинг с поддержкой скриптов на PHP и интерфейсом на cPanel (например тариф Host-A от Reg.ru). Виртуальные сервера VDS\VPS тоже подойдут, но больше времени уйдет на настройку.

Подготовка к работе с API

При создании токена отметьте следующие разрешения:

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

Покупка пакет QIWI мастер

После исполнения скрипта в браузере появится статус транзакции.

Покупка карты

Шаг 1. Создание заказа

Доступные для заказа типы карт:

Скопируйте этот код в файл cardsbuy.php и перейдите в браузере на cтраницу http://localhost/master-api/cardsbuy.php.

Шаг 2. Подтверждение заказ карты

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

Добавьте следующий код в файл cardbuy.php для подтверждения заказа карты:

Шаг 3. Покупка карты

Отправим запрос для покупки карты.

Добавьте следующий код в файл cardbuy.php для подтверждения заказа карты:

Сообщение «Accepted!» означает, что карта выпущена успешно. Любое другое сообщение значит ошибку.

Список карт с реквизитами

Скопируйте этот код в файл cardsreq.php и перейдите в браузере на cтраницу http://localhost/master-api/cardsreq.php:

В результате выполнения кода вы получите список выпущенных вирутальных карт в составе пакета QIWI Мастер.

Источник

Процесс интеграции через SDK

Ознакомьтесь с нашей документацией.

Шаг 1. Подготовка среды разработки

Выберите SDK для вашего языка программирования и перейдите в репозиторий на GitHub:

Обратите внимание, что в зависимости от выбранного вами SDK потребуется установка Composer, Apache Maven или NuGet.

Шаг 2. Создание секретного ключа

Перейдите на вкладку API.

Нажмите на кнопку Настроить и придумайте название, по которому потом сможете найти нужный API-ключ.

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

В поле URL сервера для уведомлений укажите адрес вашего сервера для обработки уведомлений об оплате.

Нажмите Создать и получите ключи авторизации.

Скопируйте себе секретный ключ (в оранжевом блоке), нажав на ссылку Скопировать в буфер. Рекомендуем не закрывать данное окно и не нажимать на кнопку Дальше, пока не настроите авторизацию.

Шаг 3. Авторизация

В разрабатываемом коде заведите константу SECRET_KEY и присвойте ей значение секретного ключа, вставив его из буфера обмена комбинацией клавиш Ctrl+V.

Раздел документации с примерами авторизации находится здесь.

Шаг 4. Выставление счета

Рекомендуем использовать дополнительные параметры:

Необязательные параметры для выставления счета:

В ответе на запрос выставления счета возвращаются следующие поля:

Для тестирования и отладки сервиса рекомендуем выставлять и оплачивать счета суммой 1 рубль.

Раздел документации с примерами выставления счетов находится здесь.

Шаг 5. Установка дополнительных параметров к ссылке на счёт

При выставлении счета через API в ответе приходит payUrl, содержащий ссылку на форму. К данной ссылке можно добавить следующие параметры:

Шаг 6. Редирект пользователя на платежную форму

Пример получения URL оплаты по счету

Реализуйте на вашем сайте перенаправление пользователя на платежную форму по ссылке, полученной в ответе на запрос выставления счёта в параметре payUrl или по ссылке с дополнительными параметрами, сформированной на шаге 5.

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

Пример передачи реферальной ссылки

Сервис уведомлений позволяет понять, когда и по какому счету произошла оплата. Вам не нужно каждый раз отправлять запросы в QIWI, можно подключить сервис и получать уведомления автоматически. Но стоит обратить внимание на то, что уведомление может быть отправлено несколько раз даже в случае успешного ответа от вашего сервиса, поэтому это необходимо учитывать при разработке бизнес-логики отгрузки товара или услуги на вашей стороне.

Формат уведомлений описан в документации.

Данные приходят в теле запроса (body). Данные запроса хранятся в формате JSON.

Так как для отладки уведомлений тестовый контур не предусмотрен, рекомендуем выставлять счета на 1 рубль и оплачивать их самостоятельно.

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

Условия интеграции с API уведомлений

Если же вы пока не можете определиться, тогда ознакомьтесь с условиями обслуживания интеграции с API уведомлений:

Мы устанавливаем на своей стороне таймаут на установление соединения – 2 секунды, и таймаут на получение ответа – также 2 секунды. Поэтому не рекомендуем внедрять долго выполняющуюся логику или логику, связанную с ожиданием (waiter, sleep), в процесс обработки уведомления.

Рекомендуем на стороне вашего сервера организовывать очередь и складывать в нее входящие запросы от QIWI с изменением статусов счетов, после чего отвечать QIWI на уведомление успешным статусом.

Обработку уведомлений в очереди и свою бизнес-логику стоит проводить в потоках, отдельных от приема уведомлений, чтобы успевать отвечать нам вовремя.

Мы не можем гарантировать exactly once доставку уведомления, т.е. вам может прийти более одного уведомления об одной и той же успешной оплате счёта.

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

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

Шаг 8*. Настройка серверных уведомлений

Уведомление представляет собой входящий POST-запрос.

Тело запроса содержит JSON-сериализованные данные счета (кодировка UTF-8).

Проверьте, что IP-адреса, с которых QIWI отправляет уведомления, находятся в списке разрешенных:

Если не приходят уведомления по счету:

Попробуйте отправить себе уведомление, заменив в примере https://test.com/notif.php на URL, который вы указали при создании ключей для получения уведомлений.

Если вы не используете облачные сервисы для приема уведомлений вроде amazon или heroku, а настраивали свой вебсервер и ssl в нем самостоятельно, проверьте ssl сертификат.

Если ssl сертификат для установления соединения по https выпущен не общеизвестным доверенным центром сертификации (например, Comodo, Verisign, Thawte и т.п.), проверьте, что ваш сервер при установке соединения отправляет полную цепочку сертификатов, включая доверенный корневой центр сертификации в начале цепочки.

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

Шаг 9*. Проверка подписи уведомлений

Настоятельно рекомендуем проверять уведомления на подлинность, т.к. мы не несем ответственность, если будут приходить поддельные уведомления от мошенников.

Формат уведомлений описан в документации.

Данные приходят в теле запроса (body). Данные запроса хранятся в формате JSON.

Алгоритм проверки подписи:

Объединить значения следующих параметров уведомления в одну строку с разделителем | :

где <*>– значение параметра. Все значения при проверке подписи должны трактоваться как строки.

Вычислить HMAC-хэш c алгоритмом хэширования SHA256:

hash = HMAС(SHA256, invoice_parameters, secret_key)

где: secret_key – секретный ключ, при помощи которого был выставлен счёт; invoice_parameters – строка из п.1.

Сравнить значение заголовка X-Api-Signature-SHA256 с результатом из п.2.

В разрабатываемом коде заведите константу merchantSecret и присвойте ей значение секретного ключа, который выпустили в личном кабинете. Значение должно быть то же самое, что в константе SECRET_KEY на шаге авторизации.

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

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

Шаг 11*. Проверка статуса перевода по счету

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

Также данный метод можно использовать как самостоятельный, т.е. после выставления счета раз в какой-то промежуток времени опрашивать статус этого счета. Этот метод проще интеграции с сервисом уведомлений.

Раздел документации с примерами проверки статуса оплаты счета находится здесь.

Шаг 12. Бизнес-логика

Счет в своем жизненном цикле проходит следующие статусы оплаты:

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

Поздравляем, интеграция с QIWI для получения платежей закончена!

Дополнительно. Шаг 13. Отмена неоплаченных счетов

Вы можете отменять неоплаченные счета самостоятельно, используя метод cancelBill.

Раздел документации с примерами запросов для отмены неоплаченных счетов находится здесь.

Источник