Токен qiwi что это
Инструкция по работе с 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 Мастер.
Введение
Последнее обновление: 2021-06-02 | Редактировать на GitHub
Сервис QIWI PAY предназначен для обслуживания операций по банковским картам. Сервис позволяет ТСП принимать безопасные платежи по картам от клиентов.
Сервис поддерживает операции выполнения платежа, подтверждения платежей, выполненных по двухшаговому сценарию, отмены платежа, возврата денежных средств, а также получения статуса операции.
Способы взаимодействия
Существует два способа работы с QIWI PAY:
URL сервисов оплаты
Возможные операции
Список доступных операций для каждого способа взаимодействия с QIWI PAY приведен в таблице.
Код операции | QIWI PAY WPF | QIWI PAY API | Операция | Финансовая | Описание |
---|---|---|---|---|---|
1 | + | + | sale | Да | Одношаговый сценарий оплаты |
2 | — | + | finish_3ds | Зависит от сценария | Возврат в систему после 3DS аутентификации |
3 | + | + | auth | Нет | Авторизационный запрос (холдирование средств) в случае двухшагового сценария оплаты |
5 | — | + | capture | Да | Подтверждение авторизации в случае двухшагового сценария оплаты |
6 | — | + | reversal | Нет | Отмена платежа (средства расхолдируются практически сразу) |
7 | — | + | refund | Да | Возврат платежа (средства возвращаются в течение 30 дней) |
20 | — | + | payout | Да | Операция выплаты (OCT ) |
30 | — | + | status | Нет | Запрос статуса операции |
40 | — | + | get_cards_by_token | нет | Получение списка привязанных карт |
Финансовая операция означает, что по результатам данной операции будет произведено движение средств по счетам.
Типы операций покупки
Методы проведения оплаты
Возможны два сценария платежа:
Чтобы точно понимать, какой тип операции можно выполнять для транзакции, необходимо запросить ее статус и действовать в соответствии с таблицей статусов.
С точки зрения наличия полей в запросе, все операции идентичны. Отличаются лишь коды операций.
Технология 3DS
QIWI PAY WPF
Клиенту отображается платежная форма для ввода реквизитов карты на стороне QIWI PAY.
Схема одношагового сценария платежа с использованием платежной формы (WPF ) на стороне QIWI PAY.
Перенаправление на платежную форму
QIWI PAY API
Авторизация
Реализация сценариев платежа
Схема одношагового сценария платежа
Схема двухшагового сценария платежа
Операция покупки
Запрос
Ответ на операцию покупки в случае не 3DS операции
Поле ответа | Тип данных | Описание |
---|---|---|
txn_id | integer | Идентификатор транзакции |
txn_status | integer | Статус транзакции |
txn_type | integer | Тип транзакции |
txn_date | YYYY-MM-DDThh:mm:ss±hh:mm | Дата транзакции в формате ISO8601 с временной зоной |
card_token | string(40) | Токен карты (если функционал токенизации включен для данного сайта) |
card_token_expire | YYYY-MM-DDThh:mm:ss±hh:mm | Срок истечения токена карты (если функционал токенизации включен для данного сайта) |
error_code | integer | Код ошибки работы системы |
pan | string(19) | Номер карты Покупателя |
issuer_name | string(40) | Название банка-эмитента |
issuer_country | string(3) | Страна банка-эмитента |
amount | decimal | Сумма списания |
currency | integer | Валюта суммы списания в цифровом формате согласно ISO 4217 |
auth_code | string(6) | Код авторизации |
eci | string(2) | Индикатор E-Commerce операции |
is_test | string(4) | Наличие этого параметра со значением true указывает на то, что транзакция проведена в тестовой среде. Реального списания д/с с карты не было. |
Ответ в случае если необходима 3DS аутентификация
Поле ответа | Тип данных | Описание |
---|---|---|
txn_id | integer | Идентификатор транзакции |
txn_status | integer | Статус транзакции |
txn_type | integer | Тип транзакции |
txn_date | YYYY-MM-DDThh:mm:ss±hh:mm | Дата транзакции в формате ISO8601 с временной зоной |
error_code | integer | Код ошибки работы системы |
acs_url | string(1024) | URL адрес банка-эмитента куда необходимо перенаправить Покупателя |
pareq | string(4096) | Уникальный идентификатор Покупателя, используемый при дальнейшем его перенаправлении на acs_url. |
is_test | string(4) | Наличие этого параметра со значением true указывает на то, что транзакция проведена в тестовой среде. Реального списания д/с с карты не было. |
Завершение 3DS аутентификации
Запрос после прохождения 3DS аутентификации
Параметр | Условие | Тип данных | Описание |
---|---|---|---|
opcode | Обязательно | integer | Код операции ( 2 ) |
merchant_site | Обязательно | integer | Идентификатор сайта ТСП |
pares | Обязательно | string(4096) | Результат верификации Покупателя |
txn_id | Обязательно | integer | Идентификатор транзакции |
sign | Обязательно | string(64) | Контрольная сумма переданных параметров |
Ответ на операцию покупки после 3DS аутентификации
Поле ответа | Тип данных | Описание |
---|---|---|
txn_id | integer | Идентификатор транзакции |
txn_status | integer | Статус транзакции |
txn_type | integer | Тип транзакции |
txn_date | YYYY-MM-DDThh:mm:ss±hh:mm | Дата транзакции в формате ISO8601 с временной зоной |
card_token | string(40) | Токен карты (если функционал токенизации включен для данного сайта) |
card_token_expire | YYYY-MM-DDThh:mm:ss±hh:mm | Срок истечения токена карты (если функционал токенизации включен для данного сайта) |
error_code | integer | Код ошибки работы системы |
pan | string(19) | Номер карты Покупателя |
issuer_name | string(40) | Название банка-эмитента |
issuer_country | string(3) | Страна банка-эмитента |
amount | decimal | Сумма списания |
currency | integer | Валюта суммы списания в цифровом формате согласно ISO 4217 |
auth_code | string(6) | Код авторизации |
eci | string(2) | Индикатор E-Commerce операции |
is_test | string(4) | Наличие этого параметра со значением true указывает на то, что транзакция проведена в тестовой среде. Реального списания д/с с карты не было. |
Операция подтверждения покупки
Запрос
Параметр | Условие | Тип данных | Описание |
---|---|---|---|
opcode | Обязательно | integer | Код операции ( 5 ) |
merchant_site | Обязательно | integer | Идентификатор сайта ТСП |
txn_id | Обязательно | integer | Идентификатор транзакции |
sign | Обязательно | string(64) | Контрольная сумма переданных параметров |
cheque | Опционально | string | Данные для кассового чека по 54-ФЗ |
Ответ
Поле ответа | Тип данных | Описание |
---|---|---|
txn_id | integer | Идентификатор транзакции |
txn_status | integer | Статус транзакции |
txn_type | integer | Тип транзакции |
txn_date | YYYY-MM-DDThh:mm:ss±hh:mm | Дата транзакции в формате ISO8601 с временной зоной |
error_code | integer | Код ошибки работы системы |
is_test | string(4) | Наличие этого параметра со значением true указывает на то, что транзакция проведена в тестовой среде. Реального списания д/с с карты не было. |
Операция отмены
Запрос
Параметр | Условие | Тип данных | Описание |
---|---|---|---|
opcode | Обязательно | integer | Код операции ( 6 ) |
merchant_site | Обязательно | integer | Идентификатор сайта ТСП |
txn_id | Обязательно | integer | Идентификатор транзакции |
sign | Обязательно | string(64) | Контрольная сумма переданных параметров |
amount | Опционально | string(20) | Сумма операции |
Ответ
Поле ответа | Тип данных | Описание |
---|---|---|
txn_id | integer | Идентификатор транзакции |
txn_status | integer | Статус транзакции |
txn_type | integer | Тип транзакции |
txn_date | YYYY-MM-DDThh:mm:ss±hh:mm | Дата транзакции в формате ISO8601 с временной зоной |
error_code | integer | Код ошибки работы системы |
amount | decimal | Сумма списания |
is_test | string(4) | Наличие этого параметра со значением true указывает на то, что транзакция проведена в тестовой среде. Реального возврата д/с на карту не было. |
Операция возврата
Запрос
Параметр | Условие | Тип данных | Описание |
---|---|---|---|
opcode | Обязательно | integer | Код операции ( 7 ) |
merchant_site | Обязательно | integer | Идентификатор сайта ТСП |
txn_id | Обязательно | integer | Идентификатор транзакции |
sign | Обязательно | string(64) | Контрольная сумма переданных параметров |
amount | Опционально | string(20) | Сумма операции |
Ответ
Поле ответа | Тип данных | Описание |
---|---|---|
txn_id | integer | Идентификатор транзакции |
txn_status | integer | Статус транзакции |
txn_type | integer | Тип транзакции |
txn_date | YYYY-MM-DDThh:mm:ss±hh:mm | Дата транзакции в формате ISO8601 с временной зоной |
error_code | integer | Код ошибки работы системы |
amount | decimal | Сумма списания |
is_test | string(4) | Наличие этого параметра со значением true указывает на то, что транзакция проведена в тестовой среде. Реального возврата д/с на карту не было. |
Операция выплаты
Запрос
Ответ
Поле ответа | Тип данных | Описание |
---|---|---|
txn_id | integer | Идентификатор транзакции |
txn_status | integer | Статус транзакции |
txn_type | integer | Тип транзакции |
txn_date | YYYY-MM-DDThh:mm:ss±hh:mm | Дата транзакции в формате ISO8601 с временной зоной |
error_code | integer | Код ошибки работы системы |
pan | string(19) | Номер карты |
amount | decimal | Сумма выплаты |
currency | integer | Валюта суммы списания в цифровом формате согласно ISO 4217 |
auth_code | string(6) | Код авторизации |
Запрос статуса операции
Запрос
Параметр | Условие | Тип данных | Описание |
---|---|---|---|
opcode | Обязательно | integer | Код операции ( 30 ) |
merchant_site | Обязательно | integer | Идентификатор сайта ТСП |
sign | Обязательно | string(64) | Контрольная сумма переданных параметров |
txn_id | Опционально | integer | Идентификатор транзакции |
order_id | Опционально | string(256) | Уникальный номер заказа в системе ТСП |
Ответ
Подпись запроса
Каждая операция должна быть подписана. Подпись помещается в параметр sign запроса.
Уведомления о платежах
Существует два метода доставки уведомлений о платеже:
Для дополнительной уверенности следует принимать уведомления о платежах только с указанных ниже IP-адресов компании QIWI.
Отраслевые данные
Авиаданные
В авиаданных должны присутствовать билеты из брони, а также все сегменты (перелеты) из каждого билета.
Параметр | Условие | Тип данных | Описание |
---|---|---|---|
type | Обязательно | string | Типы отраслевых данных ( avia ) |
pnr | Опционально | string(6) | Номер брони |
tickets | Обязательно | array | Массив билетов |
number | Обязательно | string(14) | Номер билета |
passenger_name | Обязательно | string(20) | Имя пассажира |
amount | Обязательно | decimal | Цена билета без сборов |
amount_total | Обязательно | decimal | Цена билета со сборами |
restricted | Обязательно | boolean | Restricted Ticked Indicator |
agency_code | Обязательно | string(8) | Код агентства |
agency_name | Обязательно | string(25) | Название агентства |
airport_code | Обязательно | string(3) | Аэропорт вылета (3 буквы по классификации IATA) |
segments | Обязательно | array | Массив сегментов |
amount | Обязательно | decimal | Номер билета |
service_class | Обязательно | string(1) | Класс обслуживания |
fare_basis_code | Обязательно | string(6) | Вид тарифа |
dest_city | Обязательно | string(3) | Аэропорт назначения (3 буквы по классификации IATA) |
carrier_code | Обязательно | string(2) | Код авиакомпании |
stopover_code | Обязательно | string(1) | Stop-Over Code |
departure_date | Обязательно | YYYY-MM-DDThh:mm:ss±hh:mm | Дата вылета в формате ISO8601 с временной зоной |
flight_number | Обязательно | string(5) | Номер рейса, только цифры |
Безопасная сделка
Безопасная сделка от QIWI обеспечивает прозрачный и надежный механизм оплаты работ без риска потери денег как для заказчика, так и для исполнителя. Чтобы подключить Безопасную сделку, обратитесь к вашему сопровождающему менеджеру.
Поддерживается два вида безопасной сделки:
Работа с подсуммами
Для работы по протоколу безопасной сделки вам необходимо разделять сумму авторизации на подсуммы:
Подсумма выплат — денежные средства, которые будут выплачены исполнителю при завершении безопасной сделки.
Подсумма комиссий — сумма комиссий Площадки, на которой выполняется сделка, и QIWI. Из данной подсуммы QIWI удержит комиссию за проведение операции, а остаток перечислит Площадке.
Подсуммы передаются в авторизационном запросе или в вызове WPF в поле cf2 через точку с запятой:
Безопасная сделка с выплатой на QIWI кошелек
Этот вид безопасной сделки состоит из двух этапов:
На каждом из этапов обязательно указывайте номер QIWI Кошелька в поле cf1 в формате
При подтверждении операции сумма к выплате автоматически зачислится на указанный в запросе QIWI Кошелек.
Транзакцию можно отменить полностью или частично только до подтверждения операции. Чтобы совершить отмену, выполните запрос отмены (код операции 6 ) и укажите в поле cf2 подсуммы отменяемой транзакции (в том же формате, что и при авторизации).
Безопасная сделка с выплатой на карту
Этот вид безопасной сделки состоит из трех этапов:
После подтверждения операции есть 30 дней для того, чтобы совершить операцию выплаты. Зачисление средств на карту получателя происходит в течение трех дней.
Вы можете отменить транзакцию полностью или частично до подтверждения операции, а также совершить возврат после подтверждения, если выплата еще не была совершена.
Для отмены или возврата выполните запрос отмены (код операции 6 ) или возврата (код операции 7 ) и укажите в поле cf2 подсуммы отменяемой транзакции (в том же формате, что и при авторизации).
Передача чека (54-ФЗ)
JSON структура чека должна быть сжата алгоритмом DEFLATE, описанным в RFC1951, а после представлена в ZLIB формате, описанным в RFC1950. Далее результат кодируется в BASE64 и передается в соответствующем параметре.
Параметры чека
Параметр | Условие | Тип данных | Описание |
---|---|---|---|
seller_id | Обязательно | decimal | ИНН организации, для которой пробивается чек |
cheque_type | Обязательно | decimal | Признак расчета (тэг 1054 ): 1. Приход 2. Возврат прихода 3. Расход 4. Возврат расхода |
customer_contact | Обязательно | string(64) | Телефон или электронный адрес покупателя (тэг 1008 ) |
tax_system | Обязательно | decimal | Система налогообложения (тэг 1055 ): 0 – Общая, ОСН 1 – Упрощенная доход, УСН доход 2 – Упрощенная доход минус расход, УСН доход — расход 3 – Единый налог на вмененный доход, ЕНВД 4 – Единый сельскохозяйственный налог, ЕСН 5 – Патентная система налогообложения, Патент |
positions | Обязательно | array | Массив товаров |
quantity | Обязательно | decimal | Количество предмета расчета (тэг 1023 ) |
price | Обязательно | decimal | Цена за единицу предмета расчета с учетом скидок и наценок (тэг 1079) |
tax | Обязательно | decimal | Ставка НДС (тэг 1199 ): 3 – с учетом НДС 18% (18/118) 4 – с учетом НДС 10% (10/110) 5 – ставка НДС 0% 6 – НДС не облагается 7 – с учетом НДС 20% (20/120) |
description | Обязательно | string(128) | Наименование предмета расчета |
payment_method | Обязательно | decimal | Признак способа расчёта (тэг 1214 ): 1 – предоплата 100%. Полная предварительная оплата до момента передачи предмета расчета. 2 – предоплата. Частичная предварительная оплата до момента передачи предмета расчета. 3 – аванс. 4 – полный расчет. Полная оплата, в том числе с учетом аванса (предварительной оплаты) в момент передачи предмета расчета. 5 – частичный расчет и кредит. Частичная оплата предмета расчета в момент его передачи с последующей оплатой в кредит. 6 – передача в кредит. Передача предмета расчета без его оплаты в момент его передачи с последующей оплатой в кредит. 7 – оплата кредита. Оплата предмета расчета после его передачи с оплатой в кредит (оплата кредита). |
payment_subject | Обязательно | decimal | Признак предмета расчёта (тэг 1212 ): 1 – товар. О реализуемом товаре, за исключением подакцизного товара (наименование и иные сведения, описывающие товар). 2 – подакцизный товар. О реализуемом подакцизном товаре (наименование и иные сведения, описывающие товар). 3 – работа. О выполняемой работе (наименование и иные сведения, описывающие работу). 4 – услуга. Об оказываемой услуге (наименование и иные сведения, описывающие услугу). 5 – ставка азартной игры. О приеме ставок при осуществлении деятельности по проведению азартных игр. 6 – выигрыш азартной игры. О выплате денежных средств в виде выигрыша при осуществлении деятельности по проведению азартных игр. 7 – лотерейный билет. О приеме денежных средств при реализации лотерейных билетов, электронных лотерейных билетов, приеме лотерейных ставок при осуществлении деятельности по проведению лотерей. 8 – выигрыш лотереи. О выплате денежных средств в виде выигрыша при осуществлении деятельности по проведению лотерей. 9 – предоставление результатов интеллектуальной деятельности. О предоставлении прав на использование результатов интеллектуальной деятельности или средств индивидуализации. 10 – платеж. Об авансе, задатке, предоплате, кредите, взносе в счет оплаты, пени, штрафе, вознаграждении, бонусе и ином аналогичном предмете расчета. 11 – агентское вознаграждение. О вознаграждении пользователя, являющегося платежным агентом (субагентом), банковским платежным агентом (субагентом), комиссионером, поверенным или иным агентом. 12 – составной предмет расчета. О предмете расчета, состоящем из предметов, каждому из которых может быть присвоено значение выше перечисленных признаков. 13 – иной предмет расчета. О предмете расчета, не относящемуся к выше перечисленным предметам расчета. |
Apple Pay
Apple Pay позволяет покупателям оплачивать покупки на сайте в одно касание, без ввода данных карты. Технология работает в мобильных приложениях и браузере Safari на iPhone, iPad, Apple Watch и MacBook. Для включения метода оплаты Apple Pay необходимо обратиться к вашему сопровождающему менеджеру.
Вам понадобится самостоятельно произвести интеграцию с Apple. Данная интеграция позволит верифицировать сайт ТСП и получать платежные данные пользователя.
Более подробно об интеграции можно узнать на сайте Apple.
Как отправлять платеж
Пример передачи данных от Apple
Процесс выполнения платежа Apple Pay в QIWI PAY API состоит из трех этапов:
При процессинге платежей Apple Pay на текущий момент при выполнении операции покупки поддерживаются следующие коды операций ( opcode ): sale (1) и auth (3).
Значение поля apple_pay_encoded_payment_token рассчитывается по следующему алгоритму:
value = b64_encode_bytes_to_string (compress_bytes_with_zlib (to_bytes (json)))
Пример шифрования/проверки токена Apple Pay
Шаг 1 ( to_bytes ) — Объект json конвертируется в массив байтов в соответствии с кодировкой UTF-8.
Шаг 2 ( compress_bytes_with_zlib ) — Байты, полученные на предыдущем шаге сжимаются с помощью библиотеки zlib. При сжатии необходимо следовать спецификации RFC1950 и обеспечить запись zlib header в начало потока со сжатыми данными.
Шаг 3 ( b64_encode_bytes_to_string ) — Байты, полученные на предыдущем шаге, кодируются в формат base64.
Интеграция с Google Pay™
Как отправлять данные в Google
При процессинге платежей Google Pay™ поддерживаются следующие коды операций покупки: sale (opcode: 1 ) и auth (opcode: 3 ).
Пример шифрования/проверки токена Google Pay
Значение поля google_pay_encoded_payment_token рассчитывается по следующему алгоритму:
b64_encode_bytes_to_string (compress_bytes_with_zlib (to_bytes (JSON)))
Шаг 1 ( to_bytes ) — JSON конвертируется в массив байтов в соответствии с кодировкой UTF-8.
Шаг 2 ( compress_bytes_with_zlib ) – Байты, полученные на предыдущем шаге, сжимаются с помощью библиотеки zlib. При сжатии необходимо следовать спецификации RFC1950 и обеспечить запись zlib header в начало потока со сжатыми данными.
Шаг 3 ( b64_encode_bytes_to_string ) — Байты, полученные на предыдущем шаге, кодируются в формат base64.
Ответ на запрос покупки
Типы транзакций
Тип | Название | Описание |
---|---|---|
1 | Purchase | Одношаговая операция оплаты |
2 | Purchase | Операция авторизации при двухшаговом сценарии платежа |
4 | Reversal | Операция отмены |
3 | Refund | Операция возврата |
8 | Payout | Операция выплаты (OCT ) |
0 | Unknown | Неизвестный тип операции |
Статусы транзакции
Описание ошибок
Структура ответа с ошибкой
Запрос с ошибкой карточных данных
Запрос с ошибкой (пустой номер транзакции)
Ответ с ошибкой имеет следующую структуру:
Поле | Тип | Описание |
---|---|---|
error_code | Number | Код ощибки |
error_message | String | Описание ошибки |
errors | Array of Objects | Подробное описание ошибок в параметрах |
errors[].field | String | Параметр запроса, вызвавший ошибку |
errors[].message | String | Текстовое описание ошибки |
Коды ошибок
Данные для тестирования
Для тестирования операций оплаты используются производственные URL сервисов оплаты.
Тестовые номера карт
Получить номера карт
Для тестирования различных вариантов оплаты и ответов необходимо использовать различные сроки действия карты:
На тестовой среде установлено ограничение на сумму и количество тестовых операций. По умолчанию максимальная сумма тестовых транзакций — 10 рублей. Максимум — 100 транзакций в сутки (учитываются операции за текущие сутки, время по МСК). Учитываются операции с суммой не более установленного лимита.