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

• Банковская карта: ✓ QIWI Платежная форма, ✓ Платежная форма мерчанта
• Оплата платежным токеном: ✓ QIWI Платежная форма, ✓ Платежная форма мерчанта
• Yandex Pay: ✘ QIWI Платежная форма, ✓ Платежная форма мерчанта
• Mir Pay: ✓ QIWI Платежная форма, ✓ Платежная форма мерчанта
• Оплата через СБП: ✓ QIWI Платежная форма, ✓ Платежная форма мерчанта
• Оплата с баланса КИВИ Кошелька: ✓ QIWI Платежная форма, ✓ Платежная форма мерчанта
• Оплата с баланса мобильного телефона: ✘ QIWI Платежная форма, ✓ Платежная форма мерчанта

* — метод оплаты доступен по умолчанию, другие методы оплаты подключаются по запросу.

** — требуется сертификация PCI DSS.

*** — с помощью выпуска платежного токена для кошелька QIWI.

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

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

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

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 | Обязательный параметр. Ключ идентификации мерчанта | String |
| | уникальный для каждого siteId. Ключ можно получить в | |
| | Личном кабинете в разделе Настройки. | |
| billId | Уникальный идентификатор счета в системе мерчанта. | |
| | Генерируется на вашей стороне любым способом как | String(200) |
| | уникальная последовательность букв, цифр и символов \_ | |
| | -. Если не указан, то при каждом переходе по ссылке | |
| | создается новый счет. | |
| amount | Сумма покупки, округленная в меньшую сторону до 2 | Number(6.2) |
| | десятичных знаков (всегда в рублях) | |
| currency | Код валюты покупки. Возможные значения: RUB, EUR, USD. | 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.

Авторизация уведомлений

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

Цифровая подпись уведомления помещается в HTTP-заголовок Signature.

Для проверки подписи используется механизм проверки целостности HMAC с хэш-функцией SHA256 и ключом, указанным в разделе Настройки Личного кабинета мерчанта.

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

• parameters — строка из п.1.

• Сравнить значение подписи из HTTP-заголовка Signature уведомления с результатом п.2.

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

Сервис отправки уведомлений распределяет неуспешные уведомления по очередям:

Время повторной отправки может быть увеличено.