Токен киви что это
Как легально «вскрыть» QIWI Кошелек и прокачать его по полной программе
С недавнего времени пользователям Visa QIWI Кошелька доступны новые методы API. Под катом: что это за API, зачем мы его открыли и почему стоит начать им пользоваться уже сейчас.
История появления API
Формально история нашего API началась в апреле этого года, хотя часть из входящих в него методов была доступна задолго до этого.
Массовый пользовательский сервис QIWI Кошелек постепенно переходит на архитектуру микросервисов, поэтому внутри нашей системы компоненты взаимодействуют друг с другом посредством некоего API. Любой пользователь может зайти на сайт, открыть дебаггер и просмотреть, какие запросы браузер отправляет на сервер. Минимальных навыков программиста достаточно, чтобы вытащить отправляемые запросы и использовать их в собственных решениях в обход сайта.
Желающих так схитрить оказалось довольно много. Это и студенты-энтузиасты, которым интересно поковыряться в деталях работы Кошелька, и профессиональные разработчики, желающие интегрировать отдельные функции сайта QIWI Кошелька в свои решения. В итоге параллельно с развитием сайта начала развиваться целая экосистема сторонних решений в «сером» режиме, не легализованном в пользовательском соглашении и не обеспеченным нашим саппортом.
Вот только скрипты, построенные на результатах самостоятельных исследований сайта, работают у пользователей нестабильно. Разработчики используют разные способы извлечения информации, в том числе откровенно устаревшие методы, создающие дополнительную нагрузку на наши сервера.
Чтобы упорядочить выгрузку данных с сайта, мы приняли решение легализовать ее, как это сделали в свое время в Citibank, Wargaming и Вконтакте. Мы описали наиболее современный и стабильный из существующих способов получения информации, сформировав первую версию пользовательского API.
С появлением документации для разработчиков пользователям больше не нужно разбирать наш сайт по кусочкам, рискуя наткнуться на старые протоколы. По посещаемости раздела документации мы отслеживали, насколько востребован API. Мы также разместили адрес электронной почты для обратной связи и вопросов и мониторили публикации по теме в социальных сетях и форумах. На тот момент перед нами не стояло задачи как-то продвигать API — мы хотели навести порядок и предложить сторонним разработчикам бесплатный, безопасный, проверенный способ доступа.
Публикация документации по API сама по себе никак не отразилась на работе сторонних инструментов доступа к функциям Кошелька. Мы не планировали регламентировать «самострой», но наблюдали за ситуацией, поскольку решения были построены разработчиками на свой страх и риск на основе недокументированных возможностей сервиса. И пока они не затрагивают данные наших пользователей, мы никак с ними не боремся, но стараемся выйти на контакт с их создателями и рекомендовать перейти на использование задокументированного API.
Поскольку запросы проходили через парсинг сайта, очевидно, что решения, использующие выходящие за рамки API методы, будут работать до тех пор, пока соответствующие схемы работают на сайте. Но мы надеемся, что после появления более качественного пути недокументированные решения начнут постепенно отмирать.
Проблемы первой версии
К сожалению, на момент создания первой версии API у нас еще не было отдельной системы аутентификации. Поэтому на том этапе мы использовали схему аутентификации с нашего сайта (CAS), она была разобрана по отдельным командам и опубликована на developer.qiwi.com.
Аутентификация стала ключевой проблемой первого API. Если с точки зрения сайта механизм был правильным (именно так организована аутентификация на большинстве веб-страниц, по принципу двух токенов с разным временем жизни), то пользователю пройти процедуру оказалось довольно сложно. Этот метод изначально не был ориентирован на пользователей, а служил внутренним задачам нашего сайта. В результате возникали различные сложности, к примеру, выскакивала капча «докажите, что вы не робот», что было неожиданностью для пользователей, поскольку API предполагает доступ именно при помощи автоматических систем.
Хотя публикацию открытого API мы никак не афишировали, в сети появилось несколько статей, в том числе с негативными отзывами. На адрес обратной связи api_help@qiwi.com мы получили более сотни писем, смысл которых сводился к тому, что сам по себе API хороший, но аутентификация никуда не годится. Не все пользователи понимали, почему для подключения к финансовому сервису надо проходить столь заковыристую процедуру, в то время как с Instagram или Вконтакте все намного проще. Мы разъясняли, что сложности были обусловлены именно финансовой составляющей, ведь используемый метод (как в аутентификации сайта, так и в API) не должен ставить под угрозу счета клиентов.
Анализируя обратную связь, мы увидели, что API востребован, а критика направлена в основном на систему аутентификации, и приняли решение развивать API дальше.
Обновленный API
Разработка новых методов в рамках API была поручена команде специалистов, которые делают бекэнд для сайта и мобильного приложения QIWI Кошелька. API — их ключевая компетенция, именно эта команда переводит основной сайт на архитектуру микросервисов. И API тут служит для взаимодействия основного сайта и отдельных сущностей через запросы, которые мы передаем нашим пользователям.
Чтобы доработать существующий API и добавить в него новые методы, мы тщательно проанализировали обратную связь от пользователей.
Хотя среди наших клиентов довольно много любителей-энтузиастов, склонных пробовать что-то новое, основная часть пользователей API — профессиональные разработчики, интегрирующие QIWI Кошелек в свои бизнес-процессы (причем, это не интернет-магазины — для юридических лиц у нас предусмотрен отдельный API). В основном речь идет об оптимизации работы Кошелька под собственные нужды: настройке уведомлений, автоматизации оплаты услуг и обмена цифровыми товарами между пользователями, а также других задачах, не связанных с привычной электронной коммерцией.
Опираясь на отзывы, мы предложили новую аутентификацию пользователей через API, добавили новые функции для взаимодействия с Кошельком. В первой версии у нас были описаны запрос баланса, история платежей и отправка перевода. Сейчас их дополнили запрос профиля пользователя, оплата сотовой связи, переводы в банки и на карты по номерам карт, счетов и договоров вместо полных реквизитов.
Новая аутентификация
Для построения системы аутентификации, ориентированной на API, мы использовали стандарт RFC 6749 по открытому протоколу OAuth 2.0. Чтобы аутентификация соответствовала требованиям финансового сервиса, мы обеспечили двухфакторный доступ — по паролю к Кошельку и SMS-коду. Для прохождения процедуры пользователю необходимо выпустить токен, действительный в течение одного месяца 180 дней (выпуск подтверждается SMS-сообщением). По просьбе пользователей в новой версии OAuth 2.0 мы также открыли возможность выбора прав доступа для токена. К примеру, если требуется запросить баланс или получить историю платежей, токену даются права только на чтение. Всего доступно четыре группы прав доступа:
Функция оказалась весьма востребована, менее половины токенов выпускается с полными правами (осуществление платежей), многим нужно лишь получение информации.
Профиль пользователя
Одна из новых функций, родившихся внутри нашей команды, а не из пожеланий клиентов — запрос профиля пользователя. Он позволяет получать различную информацию о Кошельке: дату регистрации, привязанный адрес электронной почты, уровень идентификации Кошелька. Последнее особенно важно для финансового сервиса, поскольку уровень идентификации определяет лимиты по операциям для кошелька. Ранее эту информацию можно было найти в настройках Кошелька на сайте qiwi.com, теперь она доступна и через API.
Отметим, что персональные данные пользователя через запрос профиля не доступны — таково требование безопасности.
Комиссионные тарифы
Следуя пожеланиям пользователей, мы добавили в API возможность запрашивать размер комиссии при проведении операций по любому из доступных поставщиков услуг. Метод этот открыт и прохождения процедуры аутентификации не требует.
Оплата сотовой связи
Еще одно нововведение, инициированное нашими пользователями, — инструмент автоматизации оплаты сотовой связи, например, для телефонов курьеров.
Фактически метод состоит из двух этапов:
Переводы в банки и на банковские карты
По аналогии с оплатой сотовой связи эта группа методов API позволяет автоматизировать переводы на банковские карты систем VISA, MasterCard и национальной платежной системы МИР по России и СНГ. Перевод осуществляется по номеру карты, по нему же определяется платежная система.
Банковский перевод — это отдельный метод, используемый для отправки денег в некоторые банки, с которыми у нас реализован онлайн-протокол моментальных переводов. В отличие от обычных денежных переводов по банковским реквизитам, для этих банков можно использовать большее количество идентификаторов клиента (номер карты, договора, счета и т. п.).
Юридическая сторона вопроса
До последнего времени доступ по API был формально запрещен. Все, что выполнялось при помощи API, делалось на свой страх и риск. Если пользователь распарсил сайт, достал из него какие-то команды, провел операции с кошельком, и у него пропали деньги, всю ответственность за последствия своих действий нес он сам. Техническая поддержка никак не участвовала в решении подобных проблем.
Чтобы таких ситуаций больше не возникало, мы внесли в пользовательское соглашение соответствующие изменения. Теперь API имеет официальный статус наравне с сайтом и мобильным приложением.
Что будет дальше?
Перечисленные методы доступа к данным уже работают, а документация по ним опубликована на сайте developer.qiwi.com.
Завершено внутреннее тестирование, и, опубликовав API, мы перешли ко второму этапу — проверке работоспособности связки «пользователь + документация + API». Этот этап должен ответить на вопросы о том, насколько понятна документация, нужны ли какие-то дополнительные пояснения и т. п. Поэтому мы предлагаем пользователям направлять отзывы на наш адрес: api_help@qiwi.com.
В ближайшей перспективе мы планируем расширить возможности API, предоставив сторонним сервисам методы для регистрации новых и аутентификации существующих пользователей в системе, а также проведения от их имени финансовых операций. Это немного иная модель взаимодействия между нами, пользователем и третьей стороной — сторонним сервисом.
Если вам интересны детали разработки новой версии API, пишите и задавайте вопросы в комментариях — мы постараемся ответить на них в наших следующих публикациях.
Внимание, конкурс
Чтобы заинтересовать разработчиков в использовании нового API, мы проводим всероссийский QIWI API Contest. Это первый конкурс в рамках QIWI Open Platform, направленный на популяризацию API компании.
Для участия в конкурсе необходимо создать Mobile First решения — чат-боты, мобильные приложения и web-продукты c использованием API QIWI Кошелька. Наши эксперты отберут наиболее проработанные решения и пригласят до 15 участников в финал конкурса, который пройдет в Москве 23 сентября.
Конкурсанты из других городов могут принять участие дистанционно. Регистрация проектов открыта и продлится до 15 сентября. Заявку на участие можно сделать на сайте QIWI API Contest через Timepad или отправить на почту apimarket@qiwi.com. Для всех вопросов мы создали специальный чат в Telegram.
Инструкция по работе с 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 транзакций в сутки (учитываются операции за текущие сутки, время по МСК). Учитываются операции с суммой не более установленного лимита.