Обзор протокола

## Забудьте о сложных способах оплаты, ведь теперь у вас есть уникальная возможность использовать QR-код Киви. Это простой и удобный способ оплаты, который позволяет вам совершать покупки быстро и безопасно.
## QR-код Киви – простой и удобный способ оплаты
QR-код Киви – это современная технология, которая позволяет считывать информацию с помощью камеры вашего смартфона и мгновенно осуществлять оплату. Вам больше не нужно запоминать длинные номера карт или вводить их вручную. Просто откройте приложение Киви, отсканируйте QR-код и подтвердите платеж всего несколькими касаниями пальцев.
## Безопасность и уверенность в оплате
Оплата через QR-код Киви – это не только просто, но и безопасно. Все платежи проходят через надежную систему шифрования, что гарантирует сохранность ваших данных. Вы можете быть уверены, что ваша информация не будет доступна посторонним лицам.
## Наслаждайтесь удобством и безопасностью
Наслаждайтесь удобством и безопасностью оплаты с помощью QR-кода Киви. Совершайте покупки в любимых магазинах, оплачивайте услуги и отправляйте деньги друзьям – все это стало проще и быстрее с QR-кодом Киви.
## Простота, удобство и безопасность
Простота, удобство и безопасность – вот что делает оплату через QR-код Киви идеальным выбором для каждого!
---
## Просто, удобно и безопасно
## Инновационный способ оплаты
Представляем Вам инновационный способ оплаты с помощью QR-кода Киви. Теперь Вы можете забыть о неудобных платежных картах и долгих процедурах ввода данных.
## Быстрые и безопасные покупки
QR-код Киви предоставляет возможность совершать быстрые и безопасные покупки всего в несколько кликов. Просто сканируйте код с помощью мобильного приложения Киви и подтверждайте платеж. Все данные уже в Вашем аккаунте Киви.
## Удобство и доступность
Система оплаты через QR-код Киви доступна в крупных торговых точках и сервисах, принимающих платежи с помощью Киви. Оплачивайте покупки, заказывайте товары и услуги, не имея при себе наличных или банковскую карту.
## Наслаждайтесь без лишних хлопот
Оплата через QR-код Киви — это еще один шаг вперед в развитии удобных и безопасных способов платежей. Экономьте время и деньги, используя QR-код Киви, и наслаждайтесь покупками без лишних хлопот.
---
## Простота и удобство
## Процесс оплаты
Оплата через QR-код Киви — это простой и удобный способ оплаты товаров и услуг. Просто сканируйте код с помощью мобильного приложения Киви и подтвердите оплату.
## Забудьте о вводе данных каждый раз
Забудьте о необходимости вводить данные своей банковской карты при совершении покупки. Отсканируйте QR-код и подтвердите оплату одним нажатием.
## Контролируйте расходы
Оплата через QR-код Киви поможет вам контролировать расходы. В мобильном приложении Киви увидите историю покупок и транзакций, легко отслеживая свои финансы.
## Безопасность и надежность
Оплата через QR-код Киви гарантирует вашу безопасность и надежность транзакций. Все платежи защищены надежной системой шифрования, что дает вам уверенность в каждой сделке.

## QR-код Киви: безопасный и удобный способ оплаты
QR-код Киви – это безопасный и надежный способ оплаты. Ваши финансовые данные защищены от несанкционированного доступа благодаря современным технологиям шифрования. Вы можете быть уверены, что ваша информация остается конфиденциальной и не попадет в руки злоумышленников.
## Безопасность и конфиденциальность
Платежи через QR-код Киви осуществляются моментально. Вы можете оплачивать товары или услуги в любое время и в любом месте, не зависимо от расстояния и времени суток. Вам не придется ожидать и тратить драгоценное время на поездку в банк или на поиск ближайшего терминала оплаты. Просто отсканируйте QR-код с помощью мобильного приложения Киви и совершите платеж всего в несколько кликов.
## Поддержка и комиссии
QR-код Киви поддерживает большинство платежных систем и валют. Вы можете осуществлять оплату как внутри России, так и за ее пределами. Комиссия за платежи через QR-код Киви низкая или отсутствует вовсе, что делает его очень выгодным и экономически выгодным решением для вашего бизнеса.
## Быстрота и эффективность
QR-код Киви предлагает уникальную возможность оплатить товар или услугу быстро и эффективно. Больше не нужно тратить время на поиск наличных денег или ввод данных банковской карты. Просто отсканируйте QR-код с помощью смартфона и совершите платеж всего в несколько касаний пальцев.
## Удобство и надежность
QR-код Киви предоставляет удобную и безопасную форму оплаты. Все данные шифруются и передаются напрямую на серверы платежной системы, исключая возможность несанкционированного доступа. Ваш платеж будет обработан мгновенно, и вы получите уведомление о его успешном завершении.
## Преимущества
Преимуществом оплаты через QR-код Киви является возможность просмотра деталей платежа прямо на экране вашего устройства. Вы всегда сможете убедиться, что сумма и получатель указаны правильно, что позволяет избежать ошибок при оплате. Кроме того, вы можете получить электронную квитанцию о проведенном платеже в любое удобное для вас время.
## Интеграция и совместимость
Интегрируйте оплату через QR-код Киви в свой бизнес без проблем и сложностей. Наша система поддерживает множество платежных партнеров, что позволяет вам легко внедрить данное решение в любую сферу деятельности. Будь то интернет-магазин, ресторан или мобильное приложение — оплата через QR-код Киви будет работать стабильно и без сбоев.

Мы гарантируем, что ваш бизнес не столкнется с проблемами совместимости. Наша система поддерживает все основные операционные системы, такие как Android, iOS и Windows, а также все популярные браузеры. Это означает, что ваши клиенты смогут совершать оплату через QR-код Киви с любого устройства, будь то смартфон, планшет или персональный компьютер.
Наша система предоставляет также возможность легкого подключения к платежным терминалам и системам учета. Вы сможете интегрировать оплату через QR-код Киви в свою POS-систему или CRM, что позволит автоматически регистрировать платежи и упростит учет финансов в вашем бизнесе. Благодаря гибким настройкам, вы сможете настроить систему согласно вашим требованиям и предпочтениям.
## Обзор протокола
Протокол приема платежей предоставляет быстрые и безопасные решения для приема и отправки платежей в интернете. Протокол дает вашим покупателям возможность использовать разнообразные методы платежей, включая:
## Термины и сокращения
- Ключ доступа к API — Символьная строка для авторизации мерчанта в API согласно стандарту OAuth 2.0 RFC 6749 RFC 6750.
- Платежный токен — Символьная строка, созданная по данным карты для безакцептных платежей.
- API: Application Programming Interface — набор готовых методов, предоставляемых приложением (системой) для использования во внешних программных продуктах.
- REST: Representational State Transfer — архитектурный стиль взаимодействия компонентов распределённого приложения в сети.
- JSON: JavaScript Object Notation — текстовый формат обмена данными, основанный на JavaScript RFC 7159.
- 3DS: 3-D Secure — протокол защиты карточных данных, используемый для аутентификации держателя банковской карты во время совершения платежной операции через интернет. QIWI поддерживает как версию 3DS 1.0, так и версию 3DS 2.0 протокола.
- ТСП, Мерчант — Торгово-сервисное предприятие.
- MPI: Merchant Plug-In — модуль, выполняющий 3DS аутентификацию покупателя.
- PCI DSS: Payment Card Industry Data Security Standard — стандарт безопасности данных индустрии платёжных карт, учреждённым международными платёжными системами Visa, MasterCard, American Express, JCB и Discover.
## Начало работы
Чтобы начать работу с Протоколом, выполните следующие шаги.
1. Оставьте заявку на подключение b2b.qiwi.com
2. Получите доступ к личному кабинету
3. Выпустите ключ доступа к API
4. Протестируйте взаимодействие

Подключение идентификатора в тестовом режиме

При подключении ваш идентификатор находится в тестовом режиме. В этом режиме вы можете проводить операции без списания средств с банковской карты. Подробнее о тестовом режиме см. в разделе Тестовый режим.

Перевод в производственный режим

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

Способы подключения

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

Доступные методы оплаты

* — метод оплаты доступен по умолчанию, другие методы оплаты подключаются по запросу.
** — требуется сертификация PCI DSS.
*** — посредством выпуска платежного токена для КИВИ кошелька.

Типы операций

В Протоколе доступны следующие операции.

Общая схема проведения платежа и взаиморасчетов

API Протокола приема платежей основано на принципах REST-архитектуры. Данные и методы считаются ресурсами, которые доступны через вызов универсальных идентификаторов ресурсов (URI).

Методы API вызываются через HTTP-запросы. Постоянная часть URL-адреса для вызова методов API.

Параметры методов помещаются в JSON-тело запроса. В GET-запросах параметры помещаются в query запроса.

Необходимо указывать Accept: application/json в заголовках запроса — API всегда возвращает ответ в формате JSON.

Методы API обеспечивают логическую идемпотентность, т. е. многократный вызов метода эквивалентен однократному. Однако ответ сервера может меняться (например, состояние счёта может измениться между запросами).

Авторизация

Пример запроса с авторизацией.

Пример заголовка авторизации.

Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9

Для авторизации запросов к API используется стандарт OAuth 2.0 согласно RFC 6750. Указывайте значение ключа доступа к API в HTTP-заголовке Authorization.

Аутентификация по цифровой подписи

Аутентификация по цифровой подписи применяется только для создания операций типа Выплата через API.
Для аутентификации по цифровой подписи мерчант должен создать пару RSA-ключей, например, с помощью утилиты OpenSSL. Закрытый ключ должен быть размером 2048 бит в PEM-формате. Мерчант должен передать в QIWI закодированный в Base64 открытый ключ, соответствующий закрытому ключу.

Как создать ключи

Алгоритм с примерами на языке Bash.

Тестирование проведения операций

При подключении идентификатора сайта партнёра siteId находится в тестовом режиме. В этом режиме партнёр может проводить операции без списания средств с банковской карты. Также можно запросить переключение в режим тестирования любого siteId партнёра, либо добавление нового siteId в режиме тестирования через сопровождающего менеджера. Для операций в тестовом режиме используются стандартные URL API Протокола. Тестовый режим для метода оплаты с баланса КИВИ Кошелька не предусмотрен.

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

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

При необходимости измените постоянный URL для обработки уведомлений с тестового (например, https://your-shop-test.ru/callbacks) на производственный (например, https://your-shop-prod.ru/callbacks) в Личном кабинете.

Оплата картой

Для тестирования различных вариантов оплаты и ответов используйте различные сроки действия карты:

Месяц срока действия карты Результат

02 Операция проведена неуспешно

03 Операция проведена успешно, задержка — 3 секунды

04 Операция проведена неуспешно, задержка — 3 секунды

Все остальные значения Операция выполняется успешно

Вы также можете проверить выпуск платежного токена. Схема выпуска в тестовом режиме идентична описанной в разделе Выпуск платежного токена карты.

Тестовые номера карт

CVV в тестовом режиме может быть любым (произвольные 3 цифры).

Тестирование операций с 3-D Secure

В тестовом режиме можно через API только выпускать QR-код СБП и запрашивать его статус. Для тестирования разных вариантов ответов указывайте разные суммы платежа (поле amount.value):

При запросе статуса платежа СБП в тестовом режиме доступно ограниченное количество статусов:

Выплаты

Для тестирования различных вариантов выплаты и ответов в тестовом режиме указывайте разные суммы платежа (поле amount.value):

Значение поля amount.value Результат

200.00 или 2.00 На инициирующий запрос выплаты возвращается status.value=WAITING, на последующие запросы статуса выплаты возвращается status.value=SUCCESS

500.00 или 5.00 На запрос выплаты возвращается status.value=DECLINED

510.00 или 5.10 На инициирующий запрос выплаты возвращается status.value=WAITING, на последующие запросы статуса выплаты возвращается status.value=DECLINED

Платеж через форму QIWI

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

Чтобы выполнить платеж через форму QIWI, выставите счет покупателю. Воспользуйтесь выставлением счета через API или перенаправьте покупателя на форму QIWI по прямой ссылке с параметрами счета.

Процесс платежа

Для мерчантов доступна интеграция без использования методов платежного API.

Параметры счета необходимо передать в ссылке на Платежную форму — см. ниже примеры и список параметров. Когда покупатель открывает ссылку, ему автоматически выставляется счет и отображается Платежная форма.

При оплате счета, выставленного таким способом, аутентификация покупателя и ее завершение выполняются автоматически (без участия мерчанта). Так как используется двухшаговая схема (авторизация платежа и подтверждение), то платеж необходимо подтвердить через Личный кабинет. Сервис QIWI ожидает подтверждения платежа в течение 72 часов. По истечении срока выполняется автоматическое подтверждение платежа.

Ссылка на форму с передачей суммы платежа

Ссылка на форму без указания суммы платежа (сумму заполняет покупатель)

Параметр ссылки Описание Тип

publicKey Обязательный параметр. Ключ идентификации мерчанта, уникальный для каждого siteId. Ключ можно получить в Личном кабинете в разделе Настройки. String

billId Уникальный идентификатор счета в системе мерчанта. Генерируется на вашей стороне любым способом как уникальная последовательность букв, цифр и символов _, -. Если не указан, то при каждом переходе по ссылке создается новый счет. URL-закодированная строка String(200)

amount Сумма покупки, округленная в меньшую сторону до 2 десятичных знаков (всегда в рублях) Number(6.2)

currency Код валюты покупки. Возможные значения: RUB, EUR, USD. По умолчанию RUB String(3)

phone Номер телефона покупателя (в международном формате) URL-закодированная строка

email E-mail покупателя URL-закодированная строка

successUrl URL для возврата на сайт мерчанта в случае успешной оплаты. Ссылку необходимо указывать в кодировке UTF-8. URL-закодированная строка

paymentMethod Платежный метод, предлагаемый покупателю по умолчанию на платежной форме. Возможные значения: CARD, SBP, QIWI_WALLET. Если указанный метод недоступен мерчанту, отображается другой доступный. По умолчанию — CARD. String

readonly_extras Список дополнительных полей, которые должны быть недоступны для изменения покупателем на платежной форме Строка, разделитель имен полей ,. Пример: cf1,cf3

Выставление счета и получение ссылки на оплату через API

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

Двухшаговый платеж

Выставление счета с оплатой через холдирование (двухшаговый платеж)

Уведомление об оплате счета

Одношаговый платеж

Выставление счета с оплатой без авторизации Покупателя (одношаговый платеж)

Платежный токен

Выставление счета с оплатой платежным токеном

Платежные токены используются для списаний с карт или QIWI кошельков без ввода реквизитов карты или номера кошелька. Метод оплаты платежным токеном по умолчанию отключен. Чтобы подключить его, обратитесь к вашему сопровождающему менеджеру.

Подробнее о выпуске платежного токена см. в этом разделе.

Чтобы покупатель смог оплатить платежным токеном:

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

Перенаправление на форму QIWI

Пример ответа с payUrl

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

По умолчанию, на Платежной форме QIWI 3-D Secure покупателя обязателен.

Пример ссылки с successUrl

К ссылке можно добавить параметры:

Параметр Описание Тип

successUrl URL для возврата на сайт мерчанта в случае успешной оплаты. Возврат произойдет после успешной 3DS аутентификации. Ссылку необходимо указывать в кодировке UTF-8. URL-закодированная строка

lang Язык платежной формы. Язык по умолчанию — русский (ru). ru, en

paymentMethod Платежный метод, предлагаемый покупателю по умолчанию на платежной форме. Если указанный метод недоступен мерчанту, отображается другой доступный. По умолчанию — CARD. CARD, SBP, QIWI_WALLET

Пример обработчика событий iframe

// Форма загружена // Попытка платежа // Платеж прошел успешно // Платеж не прошел

вы можете использовать метод postMessage для отслеживания состояния формы.

Возможные значения состояния:

Методы библиотеки позволяют открыть Платежную форму оплаты счета как всплывающее окно (popup) поверх вашего сайта. В библиотеке доступно два метода:

Для установки и подключения библиотеки добавьте скрипт в код сайта:

Пример вызова метода выставления счета

Чтобы создать счет и открыть форму оплаты, вызовите метод QiwiCheckout.createInvoice. Параметры метода:

Параметр Описание Формат

amount Обязательный параметр. Сумма, на которую выставляется счет, округленная в меньшую сторону до 2 десятичных знаков Number(6.2)

phone Номер телефона пользователя, на который выставляется счет (в международном формате) String

email E-mail пользователя, куда будет отправлена ссылка для оплаты счета String

account Идентификатор пользователя в системе мерчанта String

customFields Дополнительные данные счета. Список полей см. в описании одноименного параметра в запросе API выставления счета Object

lifetime Дата, до которой счет будет доступен для оплаты. Если счет не будет оплачен до этой даты, он получит финальный статус и последующая оплата станет невозможна. ГГГГ-ММ-ДДTччмм

Пример вызова метода открытия существующего счета

Этот метод используется, когда ссылка на Платежную форму оплаты счета получена при выставлении счета через API.

Чтобы открыть форму оплаты выставленного счета, вызовите метод QiwiCheckout.openInvoice. Параметры метода:

payUrl Обязательный параметр. URL-ссылка на Платежную форму String

Настройка Платежной формы

Внешний вид Платежной формы можно настроить в соответствии с вашим стилем, включая лого, фон и цвет кнопок. Для этого обратитесь в Службу поддержки и предоставьте следующую информацию:

Необязательные данные для настройки:

Пример передачи параметра стиля при выставлении счета через API

Чтобы применить ваш стиль на Платежной форме:

Название псевдонима стиля регистрозависимое.

Пример применения настройки к Платежной форме:

Платеж через форму мерчанта

При подключении платежей через собственную платежную форму по умолчанию доступен только способ оплаты Банковские карты. Другие способы оплаты доступны по запросу:

Чтобы создать платеж, передайте в запросе API Платеж:

Банковская карта

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

Создание платежа

Пример платежа с холдированием (двухшаговый платеж)

Пример платежа с немедленной оплатой (одношаговый платеж)

Чтобы инициировать платеж с предварительным холдированием средств на карте (двухшаговый платеж), передайте в запросе API Платеж:

Если карта, указанная клиентом, была ранее сохранена (токенизирована) на вашей стороне, должны быть добавлены дополнительные параметры в объекте paymentMethod:

В двухшаговом платеже возмещение формируется только после подтверждения платежа.

Ожидание аутентификации покупателя (3-D Secure)

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

Перенаправление для аутентификации 3-D Secure

Завершение аутентификации покупателя

Если требуется 3-D Secure аутентификация покупателя, в ответе на запрос платежа добавляется объект requirements.threeDS с полями:

Для дополнительной проверки покупателя у эмитента выполните POST-запрос на URL сервера аутентификации 3-D Secure с параметрами:

Чтобы сохранять обратную совместимость, использование протокола 3-D Secure 1.0 или 3-D Secure 2.0 не влияет на вашу интеграцию с API.

Далее информация о покупателе передаётся в платежную систему карты. Банк-эмитент либо предоставляет разрешение на списание средств без аутентификации (frictionless flow), либо принимает решение о необходимости аутентификации с помощью одноразового пароля (challenge flow). После прохождения проверки покупатель перенаправляется по адресу TermUrl с зашифрованным результатом проверки в параметре PaRes.

Чтобы завершить аутентификацию покупателя, передайте в запросе API Завершение аутентификации клиента:

Подтверждение платежа

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

Чтобы подтвердить платеж:

Использование платежного токена в запросе платежа

При оплате платёжным токеном покупатель не будет указывать свои карточные данные и проходить проверку 3-D Secure.

О выпуске платежного токена см. подробнее в этом разделе.

Чтобы инициировать платёж с оплатой платежным токеном, передайте в запросе API Платеж:

Если карта, для которой выпущен платежный токен, была уже ранее сохранена (токенизирована) на вашей стороне, должны быть добавлены дополнительные параметры в объекте paymentMethod:

Yandex Pay

Оплата покупок с Yandex Pay происходит без ввода данных карты.

Для включения способа оплаты Yandex Pay обратитесь к вашему сопровождающему менеджеру.

Как отправлять платеж

Пример платежа с данными расшифрованного платежного токена Yandex Pay (метод CLOUD_TOKEN)

Пример платежа с данными расшифрованного платежного токена Yandex Pay (метод PAN_ONLY)

Формат платежных данных зависит от способа аутентификации, указанного в поле authMethod расшифрованного платежного токена Yandex Pay:

Mir Pay

Клиент оплачивает покупку с Mir Pay без указания данных карты, через приложение Mir Pay.

Для включения способа оплаты Mir Pay обратитесь к вашему сопровождающему менеджеру.

Как отправлять платеж с расшифрованными данными

Пример оформленного платежа

Укажите в объекте paymentMethod запроса API Платёж параметры:

Как отправлять платеж с зашифрованными данными

Протокол приема платежей поддерживает списание средств с покупателя через Систему быстрых платежей (СБП). Через СБП можно выполнять платежи в пользу юридических лиц, в том числе с использованием QR-кодов.

По умолчанию прием оплаты через СБП отключен. Чтобы подключить этот способ оплаты, обратитесь к вашему сопровождающему менеджеру.

Получение QR-кода

Пример тела запроса для платежа через СБП

"Flower for my girlfriend"

Пример ответа c QR-кодом

При оплате через СБП покупатель сканирует QR-код и получает ссылку на платеж, которую можно открыть в приложении своего банка.

Для выпуска QR-кода СБП отправьте запрос API Получение QR-кода СБП. В запросе укажите:

В ответе на запрос в объекте qrCode содержатся данные QR-кода:

Статус платежа через СБП

После перехода платежа в финальный статус вы получите уведомление с указанным в исходном запросе идентификатором выпуска QR-кода в поле qrCodeUid. Актуальный статус платежа по идентификатору платежа paymentId из уведомления можно получить через API.

Статус QR-кода

Пример ответа на запрос статуса QR-кода

Используйте запрос Статус QR-кода СБП. В ответе возвращается информация о QR-коде, в том числе его текущий статус. Так вы можете определить действует ли QR-код.

Оплата токеном через СБП

Пример тела запроса оплаты токеном СБП

О выпуске платежного токена читайте подробнее в этом разделе.

Воспользуйтесь методом API Платеж токеном СБП и передайте в запросе:

Тестирование оплаты СБП

См. информацию в этом разделе.

Оплата со счета мобильного телефона

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

Для включения этого способа оплаты обратитесь к вашему сопровождающему менеджеру.

При отправке платежа укажите в блоке paymentMethod в запросе API Платеж параметры:

Серверные уведомления

Уведомление от QIWI — это входящий POST-запрос с информацией о событии. Тело запроса содержит JSON-сериализованные данные платежа/счета (кодировка UTF-8).

Протокол поддерживает следующие типы уведомлений о событиях API:

Адрес вашего сервера для обработки уведомлений указывается в Личном кабинете в разделе Настройки.

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

URL для уведомлений должен начинаться с https, так как уведомления отправляются по протоколу HTTPS на порт 443. URL должен быть доступен из Интернета.

Сертификат сайта должен быть выпущен доверенным центром сертификации (например Comodo, Verisign, Thawte и т.п.).

Уведомление считается успешно доставленным, если ваш сервер ответил HTTP кодом состояния 200 OK.