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

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

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

Термины и сокращения

• Ключ доступа к 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. Получите доступ к личному кабинету

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

Шаг 3. Выпустите ключ доступа к API

Ключ доступа к API используется для взаимодействия с API. Выпустите ключ API в Личном кабинете в разделе Настройки.

Шаг 4. Протестируйте взаимодействие

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

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

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

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

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

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

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

*** — through the issuance of a payment token for the QIWI wallet.

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

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

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

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) в Личном кабинете.

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

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

Руководство по тестированию QIWI API

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

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

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

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

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

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

Выплаты

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

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

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

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

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

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

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

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

Ссылки для формы QIWI

• Ссылка на форму с передачей суммы платежа
• Ссылка на форму без указания суммы платежа

Параметры ссылки:

• publicKey: Обязательный параметр. Ключ идентификации мерчанта, уникальный для каждого siteId.
• billId: Уникальный идентификатор счета в системе мерчанта.
• amount: Сумма покупки, всегда в рублях.
• currency: Код валюты покупки (RUB, EUR, USD).

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

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

Пример обработчика событий 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
Чтобы применить ваш стиль на Платежной форме:
Название псевдонима стиля регистрозависимое.
Пример применения настройки к Платежной форме:
![](https://developer.qiwi.com/images/payin/qiwi-form-custom.png)
## Платеж через форму мерчанта
При подключении платежей через собственную платежную форму по умолчанию доступен только способ оплаты Банковские карты. Другие способы оплаты доступны по запросу:
Чтобы создать платеж, передайте в запросе 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.
## Частота отправки уведомлений
Сервис отправки уведомлений распределяет неуспешные уведомления по очередям:
Время повторной отправки может быть увеличено.