Инструкция по работе с 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 Мастер.
API QIWI Кассы
Последнее обновление: 2019-03-20 | Редактировать на GitHub
Для работы API потребуются публичный и секретный ключи. Ключи создаются в личном кабинете после регистрации и подключения на kassa.qiwi.com или p2p.qiwi.com.
Схема работы
Пользователь формирует заказ на сайте мерчанта.
Мерчант перенаправляет пользователя на Платежную форму для выставления счета по заказу. Или выставляет счет по API и перенаправляет пользователя на созданную платежную форму.
Пользователь выбирает способ оплаты и оплачивает счет. По умолчанию подбирается оптимальный для пользователя способ оплаты.
После оплаты счета мерчант получает уведомление (предварительно настройте отправку уведомлений в Личном кабинете). Уведомления об оплате счета содержат параметры авторизации, которые необходимо проверять на сервере мерчанта.
Также есть возможность
Авторизация
Запросы мерчанта авторизуются посредством секретного ключа API (SECRET_KEY). Параметр авторизации указывается в заголовке Authorization, значение которого формируется как «Bearer SECRET_KEY».
Публичный ключ (PUBLIC_KEY) используется для выставления счетов через веб-форму.
Ключи создаются в личном кабинете после регистрации и подключения на kassa.qiwi.com или p2p.qiwi.com.
Взаимодействие через API
1. Выставление счета
Запрос → PUT
HEADERS
Ответ ←
Пример тела ответа при ошибке
HEADERS
2. Уведомления об оплате счетов
Запрос ← POST
Уведомление представляет собой входящий POST-запрос.
Тело запроса содержит JSON-сериализованные данные счета (кодировка UTF-8).
Адрес сервера для уведомлений указывается на сайте kassa.qiwi.com в разделе «Настройка протокола» или на p2p.qiwi.com при генерации ключей.
HEADERS
Авторизация уведомлений
Алгоритм проверки подписи:
Объединить значения параметров в одну строку с разделителем | :
где <*>– значение параметра уведомления. Все значения при проверке подписи должны трактоваться как строки.
Вычислить HMAC-хэш c алгоритмом хэширования SHA256:
hash = HMAС(SHA256, invoice_parameters, secret_key) Где:
Сравнить значение заголовка X-Api-Signature-SHA256 с результатом из п.2.
Строка и ключ подписи кодируются в UTF-8.
Параметры
В POST-запросе уведомления указаны параметры счета.
| Параметр | Описание | Тип |
|---|---|---|
| bill | Данные о счете | Object |
| billId | Уникальный идентификатор счета в системе мерчанта | String(200) |
| siteId | Идентификатор сайта мерчанта в QIWI Кассе | String |
| amount | Данные о сумме счета | Object |
| amount.value | Сумма счета, округленная до двух десятичных знаков в меньшую сторону | Number(6.2) |
| amount.currency | Идентификатор валюты счета (Alpha-3 ISO 4217 код) | String(3) |
| status | Данные о статусе счета | Object |
| status.value | Строковое значение статуса | String |
| status.changedDateTime | Дата обновления статуса. Формат даты ГГГГ-ММ-ДДTЧЧ:ММ:ССZ | String |
| customer | Данные о пользователе, на которого был выставлен счет | Object |
| customer.phone | Номер телефона, на который был выставлен счет (если был указан при выставлении счета) | String |
| customer.email | E-mail пользователя (если был указан при выставлении счета) | String |
| customer.account | Идентификатор пользователя в системе мерчанта (если был указан при выставлении счета) | String |
| creationDateTime | Дата создания счета. Формат даты ГГГГ-ММ-ДДTЧЧ:ММ:ССZ | String |
| expirationDateTime | Срок оплаты счета. Формат даты ГГГГ-ММ-ДДTЧЧ:ММ:СС+ЧЧ:ММ\-Z | String |
| comment | Комментарий к счету | String(255) |
| customFields | Дополнительные данные счета (если были указаны при выставлении счета). | Object |
| version | Версия уведомлений | String |
Ответ →
HEADERS
После того, как был получен входящий запрос-уведомление, необходимо проверить подлинность цифровой подписи и отправить ответ.
3. Проверка статуса оплаты счета
Метод позволяет проверить статус оплаты счета клиентом. Рекомендуется его использовать после получения уведомления об оплате.
Запрос → GET
URL https://api.qiwi.com/partner/bill/v1/bills/ HEADERS
Ответ ←
Пример тела ответа при ошибке
HEADERS
4. Отмена неоплаченного счета
Пример тела ответа при ошибке
Метод позволяет отменить неоплаченный счет.
Запрос → POST
URL https://api.qiwi.com/partner/bill/v1/bills//reject
HEADERS
Ответ ←
Пример тела ответа при ошибке
HEADERS
5. Возврат средств
Метод позволяет сделать возврат средств по оплаченному счету.
Запрос → PUT
URL https://api.qiwi.com/partner/bill/v1/bills//refunds/ HEADERS
Ответ ←
Пример тела ответа при ошибке
HEADERS
6. Статус возврата
Метод запрашивает статус возврата по оплаченному счету.
Запрос → GET
URL https://api.qiwi.com/partner/bill/v1/bills//refunds/ HEADERS
Ответ ←
Пример тела ответа при ошибке
HEADERS
Статусы оплаты счетов
Статус Описание Финальный WAITING Счет выставлен, ожидает оплаты — PAID Счет оплачен + REJECTED Счет отклонен + EXPIRED Время жизни счета истекло. Счет не оплачен +
Статусы операции возврата
Статус Описание Финальный PARTIAL Частичный возврат суммы — FULL Полный возврат суммы +
Дополнительно
Выставление счета через платежную форму
Простой способ для интеграции. При открытии формы клиенту автоматически выставляется счет. Параметры счета передаются в открытом виде в ссылке. Далее клиенту отображается платежная форма с выбором способа оплаты. При использовании этого способа нельзя гарантировать, что все счета выставлены мерчантом, в отличие от выставления по API.
REDIRECT →
URL https://oplata.qiwi.com/create
Параметры
В ссылке на веб-форму указываются параметры счета.
Параметр Описание Тип Обяз. publicKey Ключ идентификации мерчанта, полученный в QIWI Кассе String + billId Уникальный идентификатор счета в системе мерчанта URL-закодированная строка String(200) — amount Сумма, на которую выставляется счет, округленная в меньшую сторону до 2 десятичных знаков Number(6.2) — phone Номер телефона пользователя, на который выставляется счет (в международном формате) URL-закодированная строка — email E-mail пользователя, куда будет отправлена ссылка для оплаты счета URL-закодированная строка — account Идентификатор пользователя в системе мерчанта URL-закодированная строка — comment Комментарий к счету URL-закодированная строка String(255) — customFields[] Дополнительные данные счета URL-закодированная строка String(255) — lifetime Дата, до которой счет будет доступен для оплаты. Если счет не будет оплачен до этой даты, ему присваивается финальный статус EXPIRED и последующая оплата станет невозможна.
Внимание! По истечении 45 суток от даты выставления счет автоматически будет переведен в финальный статус URL-закодированная строка
ГГГГ-ММ-ДДTччмм — successUrl URL для переадресации в случае успешной оплаты с баланса QIWI Кошелька. При ином способе оплаты переадресация не выполняется. Ссылка должна вести на сайт мерчанта. URL-закодированная строка —
Персонализация
Персонализация позволяет адаптировать платежную форму под ваш стиль. Настраивается лого, фон и цвет кнопок.
Создать стили можно в личном кабинете. Возможно создать несколько стилей.
При настройке задается код, привязанный к стилю (например, кодСтиля ). Для использования стиля на платежной форме необходимо передать в параметре customFields запроса создания счета или вызова платежной формы переменную: «themeCode»:»кодСтиля» с соответствующим кодом стиля.
Пример передачи параметра при работе с формой
Пример передачи параметра при работе через API
Checkout Popup
Пример работы popup
Всплывающее окно (popup) позволяет открыть форму оплаты поверх вашего сайта. В библиотеке доступно два метода: создание нового счета и открытие существующего.
Установка и подключение:
Выставление нового счета
Пример выставления счета через popup
Параметр Описание Тип Обязательное publicKey Ключ идентификации мерчанта, полученный в QIWI Кассе String + amount Сумма, на которую выставляется счет, округленная в меньшую сторону до 2 десятичных знаков Number(6.2) + phone Номер телефона пользователя, на который выставляется счет (в международном формате) String — email E-mail пользователя, куда будет отправлена ссылка для оплаты счета String — account Идентификатор пользователя в системе мерчанта String — comment Комментарий к счету String(255) — customFields Дополнительные данные счета Object — lifetime Дата, до которой счет будет доступен для оплаты. Если счет не будет оплачен до этой даты, ему присваивается финальный статус EXPIRED и последующая оплата станет невозможна. Строка в виде ГГГГ-ММ-ДДTччмм —
Открытие существующего счета
Пример открытия уже созданного счета в popup
Возможности при открытии ссылки счета
При выставлении счета через API в ответе приходит payUrl с ссылкой на форму оплаты. К ссылке можно добавить следующие параметры:
Готовые решения
SDK и библиотеки
Решения для CMS
Рекомендации к оформлению
Иконки
Данные рекомендации помогут вашим пользователям быстрее сориентироваться на странице выбора способов оплаты.
Допустимо отображение 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. Бизнес-логика
Счет в своем жизненном цикле проходит следующие статусы оплаты:
Статус Описание Комментарий WAITING Счет выставлен, ожидает оплаты Нефинальный, ожидание оплаты или истечения срока действия PAID Счет оплачен Финальный (измениться не может) REJECTED Счет отклонен Финальный (измениться не может) EXPIRED Время жизни счета истекло. Счет не оплачен Финальный (измениться не может)
Опираясь на статус счета, полученный в уведомлении или при помощи поллинга статуса, доработайте бизнес-логику вашего сайта.
Поздравляем, интеграция с QIWI для получения платежей закончена!
Дополнительно. Шаг 13. Отмена неоплаченных счетов
Вы можете отменять неоплаченные счета самостоятельно, используя метод cancelBill.
Раздел документации с примерами запросов для отмены неоплаченных счетов находится здесь.
HEADERS
Ответ ←
Пример тела ответа при ошибке
HEADERS
6. Статус возврата
Метод запрашивает статус возврата по оплаченному счету.
Запрос → GET
URL https://api.qiwi.com/partner/bill/v1/bills//refunds/ HEADERS
Ответ ←
Пример тела ответа при ошибке
HEADERS
Статусы оплаты счетов
Статус Описание Финальный WAITING Счет выставлен, ожидает оплаты — PAID Счет оплачен + REJECTED Счет отклонен + EXPIRED Время жизни счета истекло. Счет не оплачен +
Статусы операции возврата
Статус Описание Финальный PARTIAL Частичный возврат суммы — FULL Полный возврат суммы +
Дополнительно
Выставление счета через платежную форму
Простой способ для интеграции. При открытии формы клиенту автоматически выставляется счет. Параметры счета передаются в открытом виде в ссылке. Далее клиенту отображается платежная форма с выбором способа оплаты. При использовании этого способа нельзя гарантировать, что все счета выставлены мерчантом, в отличие от выставления по API.
REDIRECT →
URL https://oplata.qiwi.com/create
Параметры
В ссылке на веб-форму указываются параметры счета.
Параметр Описание Тип Обяз. publicKey Ключ идентификации мерчанта, полученный в QIWI Кассе String + billId Уникальный идентификатор счета в системе мерчанта URL-закодированная строка String(200) — amount Сумма, на которую выставляется счет, округленная в меньшую сторону до 2 десятичных знаков Number(6.2) — phone Номер телефона пользователя, на который выставляется счет (в международном формате) URL-закодированная строка — email E-mail пользователя, куда будет отправлена ссылка для оплаты счета URL-закодированная строка — account Идентификатор пользователя в системе мерчанта URL-закодированная строка — comment Комментарий к счету URL-закодированная строка String(255) — customFields[] Дополнительные данные счета URL-закодированная строка String(255) — lifetime Дата, до которой счет будет доступен для оплаты. Если счет не будет оплачен до этой даты, ему присваивается финальный статус EXPIRED и последующая оплата станет невозможна.
Внимание! По истечении 45 суток от даты выставления счет автоматически будет переведен в финальный статус URL-закодированная строка
ГГГГ-ММ-ДДTччмм — successUrl URL для переадресации в случае успешной оплаты с баланса QIWI Кошелька. При ином способе оплаты переадресация не выполняется. Ссылка должна вести на сайт мерчанта. URL-закодированная строка —
Персонализация
Персонализация позволяет адаптировать платежную форму под ваш стиль. Настраивается лого, фон и цвет кнопок.
Создать стили можно в личном кабинете. Возможно создать несколько стилей.
При настройке задается код, привязанный к стилю (например, кодСтиля ). Для использования стиля на платежной форме необходимо передать в параметре customFields запроса создания счета или вызова платежной формы переменную: «themeCode»:»кодСтиля» с соответствующим кодом стиля.
Пример передачи параметра при работе с формой
Пример передачи параметра при работе через API
Checkout Popup
Пример работы popup
Всплывающее окно (popup) позволяет открыть форму оплаты поверх вашего сайта. В библиотеке доступно два метода: создание нового счета и открытие существующего.
Установка и подключение:
Выставление нового счета
Пример выставления счета через popup
Параметр Описание Тип Обязательное publicKey Ключ идентификации мерчанта, полученный в QIWI Кассе String + amount Сумма, на которую выставляется счет, округленная в меньшую сторону до 2 десятичных знаков Number(6.2) + phone Номер телефона пользователя, на который выставляется счет (в международном формате) String — email E-mail пользователя, куда будет отправлена ссылка для оплаты счета String — account Идентификатор пользователя в системе мерчанта String — comment Комментарий к счету String(255) — customFields Дополнительные данные счета Object — lifetime Дата, до которой счет будет доступен для оплаты. Если счет не будет оплачен до этой даты, ему присваивается финальный статус EXPIRED и последующая оплата станет невозможна. Строка в виде ГГГГ-ММ-ДДTччмм —
Открытие существующего счета
Пример открытия уже созданного счета в popup
Возможности при открытии ссылки счета
При выставлении счета через API в ответе приходит payUrl с ссылкой на форму оплаты. К ссылке можно добавить следующие параметры:
Готовые решения
SDK и библиотеки
Решения для CMS
Рекомендации к оформлению
Иконки
Данные рекомендации помогут вашим пользователям быстрее сориентироваться на странице выбора способов оплаты.
Допустимо отображение 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. Бизнес-логика
Счет в своем жизненном цикле проходит следующие статусы оплаты:
Статус Описание Комментарий WAITING Счет выставлен, ожидает оплаты Нефинальный, ожидание оплаты или истечения срока действия PAID Счет оплачен Финальный (измениться не может) REJECTED Счет отклонен Финальный (измениться не может) EXPIRED Время жизни счета истекло. Счет не оплачен Финальный (измениться не может)
Опираясь на статус счета, полученный в уведомлении или при помощи поллинга статуса, доработайте бизнес-логику вашего сайта.
Поздравляем, интеграция с QIWI для получения платежей закончена!
Дополнительно. Шаг 13. Отмена неоплаченных счетов
Вы можете отменять неоплаченные счета самостоятельно, используя метод cancelBill.
Раздел документации с примерами запросов для отмены неоплаченных счетов находится здесь.
HEADERS
Ответ ←
Пример тела ответа при ошибке
HEADERS
Статусы оплаты счетов
| Статус | Описание | Финальный |
|---|---|---|
| WAITING | Счет выставлен, ожидает оплаты | — |
| PAID | Счет оплачен | + |
| REJECTED | Счет отклонен | + |
| EXPIRED | Время жизни счета истекло. Счет не оплачен | + |
Статусы операции возврата
| Статус | Описание | Финальный |
|---|---|---|
| PARTIAL | Частичный возврат суммы | — |
| FULL | Полный возврат суммы | + |
Дополнительно
Выставление счета через платежную форму
Простой способ для интеграции. При открытии формы клиенту автоматически выставляется счет. Параметры счета передаются в открытом виде в ссылке. Далее клиенту отображается платежная форма с выбором способа оплаты. При использовании этого способа нельзя гарантировать, что все счета выставлены мерчантом, в отличие от выставления по API.
REDIRECT →
URL https://oplata.qiwi.com/create
Параметры
В ссылке на веб-форму указываются параметры счета.
| Параметр | Описание | Тип | Обяз. |
|---|---|---|---|
| publicKey | Ключ идентификации мерчанта, полученный в QIWI Кассе | String | + |
| billId | Уникальный идентификатор счета в системе мерчанта | URL-закодированная строка String(200) | — |
| amount | Сумма, на которую выставляется счет, округленная в меньшую сторону до 2 десятичных знаков | Number(6.2) | — |
| phone | Номер телефона пользователя, на который выставляется счет (в международном формате) | URL-закодированная строка | — |
| E-mail пользователя, куда будет отправлена ссылка для оплаты счета | URL-закодированная строка | — | |
| account | Идентификатор пользователя в системе мерчанта | URL-закодированная строка | — |
| comment | Комментарий к счету | URL-закодированная строка String(255) | — |
| customFields[] | Дополнительные данные счета | URL-закодированная строка String(255) | — |
| lifetime | Дата, до которой счет будет доступен для оплаты. Если счет не будет оплачен до этой даты, ему присваивается финальный статус EXPIRED и последующая оплата станет невозможна. Внимание! По истечении 45 суток от даты выставления счет автоматически будет переведен в финальный статус | URL-закодированная строка ГГГГ-ММ-ДДTччмм | — |
| successUrl | URL для переадресации в случае успешной оплаты с баланса QIWI Кошелька. При ином способе оплаты переадресация не выполняется. Ссылка должна вести на сайт мерчанта. | URL-закодированная строка | — |
Персонализация
Персонализация позволяет адаптировать платежную форму под ваш стиль. Настраивается лого, фон и цвет кнопок.
Создать стили можно в личном кабинете. Возможно создать несколько стилей.
При настройке задается код, привязанный к стилю (например, кодСтиля ). Для использования стиля на платежной форме необходимо передать в параметре customFields запроса создания счета или вызова платежной формы переменную: «themeCode»:»кодСтиля» с соответствующим кодом стиля.
Пример передачи параметра при работе с формой
Пример передачи параметра при работе через API
Checkout Popup
Пример работы popup
Всплывающее окно (popup) позволяет открыть форму оплаты поверх вашего сайта. В библиотеке доступно два метода: создание нового счета и открытие существующего.
Установка и подключение:
Выставление нового счета
Пример выставления счета через popup
| Параметр | Описание | Тип | Обязательное |
|---|---|---|---|
| publicKey | Ключ идентификации мерчанта, полученный в QIWI Кассе | String | + |
| amount | Сумма, на которую выставляется счет, округленная в меньшую сторону до 2 десятичных знаков | Number(6.2) | + |
| phone | Номер телефона пользователя, на который выставляется счет (в международном формате) | String | — |
| E-mail пользователя, куда будет отправлена ссылка для оплаты счета | String | — | |
| account | Идентификатор пользователя в системе мерчанта | String | — |
| comment | Комментарий к счету | String(255) | — |
| customFields | Дополнительные данные счета | Object | — |
| lifetime | Дата, до которой счет будет доступен для оплаты. Если счет не будет оплачен до этой даты, ему присваивается финальный статус EXPIRED и последующая оплата станет невозможна. | Строка в виде ГГГГ-ММ-ДДTччмм | — |
Открытие существующего счета
Пример открытия уже созданного счета в popup
Возможности при открытии ссылки счета
При выставлении счета через API в ответе приходит payUrl с ссылкой на форму оплаты. К ссылке можно добавить следующие параметры:
Готовые решения
SDK и библиотеки
Решения для CMS
Рекомендации к оформлению
Иконки
Данные рекомендации помогут вашим пользователям быстрее сориентироваться на странице выбора способов оплаты.
Допустимо отображение 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. Бизнес-логика
Счет в своем жизненном цикле проходит следующие статусы оплаты:
| Статус | Описание | Комментарий |
|---|---|---|
| WAITING | Счет выставлен, ожидает оплаты | Нефинальный, ожидание оплаты или истечения срока действия |
| PAID | Счет оплачен | Финальный (измениться не может) |
| REJECTED | Счет отклонен | Финальный (измениться не может) |
| EXPIRED | Время жизни счета истекло. Счет не оплачен | Финальный (измениться не может) |
Опираясь на статус счета, полученный в уведомлении или при помощи поллинга статуса, доработайте бизнес-логику вашего сайта.
Поздравляем, интеграция с QIWI для получения платежей закончена!
Дополнительно. Шаг 13. Отмена неоплаченных счетов
Вы можете отменять неоплаченные счета самостоятельно, используя метод cancelBill.
Раздел документации с примерами запросов для отмены неоплаченных счетов находится здесь.