Qiwi p2p что это значит

Условия использования

Последнее обновление: 09-09-2021

Для подключения на свой сайт сервиса приема переводов для физических лиц p2p необходимо иметь QIWI Кошелек со статусом идентификации «Основной» или «Профессиональный». Если Ваш кошелек имеет статус «Анонимный» – пройдите идентификацию удобным для вас способом. Для получения «Основного» статуса достаточно указать паспортные данные, для получения «Профессионального» статуса необходимо пройти очную идентификацию.

Рекомендуем получить «Профессиональный» статус. Такой статус имеет повышенные лимиты на остаток на балансе, сумму платежей и переводов в месяц, максимальную сумму одной операции. Подробнее про лимиты.

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

Активация p2p

• Авторизуйтесь на p2p.qiwi.com
• Убедитесь, что вам доступно выставление счетов – в форме Выставить счет заполните поле Сумма и нажмите на кнопку. Ниже должна появиться ссылка на счет и кнопка Скопировать ссылку.

Поздравляем! Вы можете приступить к интеграции.

Для работы API потребуются публичный и секретный ключи. Ключи создаются в разделе «API».

Схема работы с API

Пользователь формирует счет на вашей стороне.

Вы перенаправляете пользователя на платежную форму для выставления счета. Или выставляете счет по API и перенаправляете пользователя на созданную платежную форму.

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

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

Готовые решения

SDK и библиотеки

• NODE JS SDK — Готовое решение для разработки server2server интеграции c помощью Node.js.
• PHP SDK — Готовое решение для разработки server2server интеграции c помощью PHP.
• Java SDK — Готовое решение для разработки server2server интеграции c помощью Java.
• .Net SDK — Готовое решение для разработки server2server интеграции c помощью C# .Net.

С руководством по работе с SDK можно ознакомиться здесь.

Решения для CMS

• WordPress — расширение под Woocommerce для работы с заказами
• Онлайн Лейка — WordPress расширение для благотворительности
• 1С-Битрикс — решение для работы с заказами
• Opencart — решение для работы с заказами
• PrestaShop — решение для работы с заказами

Авторизация

Ваши запросы авторизуются посредством секретного ключа API ( SECRET_KEY ). Параметр авторизации указывается в заголовке Authorization, значение которого формируется как «Bearer SECRET_KEY».

Публичный ключ ( PUBLIC_KEY ) используется для выставления счетов через форму.

Ключи создаются в личном кабинете на вкладке API после авторизации на p2p.qiwi.com.

Для выпуска пары ключей выполните следующие шаги:

Авторизуйтесь в личном кабинете https://p2p.qiwi.com/ и перейдите на вкладку API.

Внизу страницы нажмите на кнопку Настроить.

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

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

В поле URL сервера для уведомлений укажите адрес вашего сервера, который будет обрабатывать уведомления об оплате, и нажмите на кнопку Создать.

Скопируйте в буфер секретный ключ и сохраните его в безопасном месте — в дальнейшем он не будет отображаться в интерфейсе. Используйте секретный ключ для запросов к API.

Выставление счета через форму

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

REDIRECT →

URL https://oplata.qiwi.com/create

Параметры

В ссылке на веб-форму указываются параметры счета.

Параметр	Описание	Тип	Обяз.
publicKey	Ваш ключ идентификации полученный в p2p.qiwi.com	String	+
billId	Идентификатор выставляемого счета в вашей системе. Он должен быть уникальным и генерироваться на вашей стороне любым способом. Идентификатором может быть любая уникальная последовательность букв или цифр. Также разрешено использование символа подчеркивания ( _ ) и дефиса ( — ).	String(200)	—
amount	Сумма, на которую выставляется счет, округленная в меньшую сторону до 2 десятичных знаков	Number(6.2)	—
phone	Номер телефона пользователя (в международном формате)	URL-Encoded String	—
email	E-mail пользователя	URL-Encoded String	—
account	Идентификатор пользователя в вашей системе	URL-Encoded String	—
comment	Комментарий к счету	URL-Encoded String(255)	—
customFields[]	Дополнительные данные счета	URL-Encoded String(255)	—
customFields[paySourcesFilter]	При открытии формы будут отображаться только указанные способы перевода (один или несколько), если они доступны. Возможные значения: qw — QIWI Кошелек card — банковская карта	URL-Encoded String	—
customFields[themeCode]	Настройка персонализации вашей формы	String(255)	—
lifetime	Дата, до которой счет будет доступен для перевода. Если перевод по счету не будет произведен до этой даты, ему присваивается финальный статус EXPIRED и последующий перевод станет невозможен. Внимание! По истечении 45 суток от даты выставления счет автоматически будет переведен в финальный статус	URL-Encoded String ГГГГ-ММ-ДДTччмм	—
successUrl	URL для переадресации на ваш сайт в случае успешного перевода	URL-Encoded String	—

Взаимодействие через API

1. Выставление счета

Доступно выставление счетов в рублях и тенге.

Надежный способ для интеграции. Параметры передаются server2server с использованием авторизации.

Метод позволяет выставить счет: при успешном выполнении запроса в ответе вернется параметр
payUrl — ссылка для перенаправления пользователя на форму. К ней вы можете добавить дополнительные параметры — подробнее в разделе Настройки формы и счета.

Также существует более простой способ выставления счета — непосредственно через вызов платежной формы

Запрос → PUT

URL https://api.qiwi.com/partner/bill/v1/bills/

• billId — сгенерированный вами идентификатор счета. Он должен быть уникальным и генерироваться на вашей стороне любым способом. Идентификатором может быть любая уникальная последовательность букв или цифр. Также разрешено использование символа подчеркивания (_) и дефиса (-).

• HEADERS

  • Authorization: Bearer SECRET_KEY
  • Content-Type: application/json
  • Accept: application/json

Параметр	Описание	Тип	Обяз.
amount	Данные о сумме счета	Object	+
amount.value	Сумма, на которую выставляется счет, округленная в меньшую сторону до 2 десятичных знаков	Number(6.2)	+
amount.currency	Валюта суммы счета. Возможные значения: RUB — рубли KZT — тенге	Alpha-3 ISO 4217 код	+
expirationDateTime	Дата, до которой счет будет доступен для оплаты. Если перевод не будет совершен до этой даты, ему присваивается финальный статус EXPIRED и последующий перевод станет невозможен.	ГГГГ-ММ-ДДTчч:мм:сс+\-чч:мм	+
customer	Идентификаторы пользователя	Object	—
customer.phone	Номер телефона пользователя (в международном формате)	String	—
customer.email	E-mail пользователя	String	—
customer.account	Идентификатор пользователя в вашей системе	String	—
comment	Комментарий к счету	String(255)	—
customFields	Дополнительные данные счета. Вы можете здесь передавать свои дополнительные поля с данными, например, SteamId	Object	—
customFields.paySourcesFilter	При открытии формы будут отображаться только указанные способы перевода (один или несколько), если они доступны. Возможные значения: qw — QIWI Кошелек card — банковская карта	Строка с разделителями-запятыми	—
customFields.themeCode	Настройка персонализации вашей формы	String(255)	—

Ответ ←

Пример тела ответа при ошибке

HEADERS

• Content-Type: application/json

Поле	Тип	Описание
siteId	String	Ваш идентификатор в сервисе приема платежей для физических лиц p2p.qiwi.com
billId	String	Уникальный идентификатор счета в вашей системе, указанный при выставлении
amount	Object	Данные о сумме счета
amount.value	Number	Сумма счета, округленная до 2 знаков после запятой в меньшую сторону
amount.currency	String	Валюта суммы счета (Alpha-3 ISO 4217 код)
status	Object	Данные о статусе счета
status.value	String	Текущий статус счета
status.changedDateTime	String	Дата обновления статуса. Формат даты: ГГГГ-ММ-ДДTчч:мм:сс+\-чч:мм
customFields	Object	Объект строковых дополнительных параметров. Возможные опции: paySourcesFilter , themeCode
customer	Object	Идентификаторы пользователя. Возможные опции: email , phone , account
comment	String	Комментарий к счету
creationDateTime	String	Системная дата создания счета. Формат даты: ГГГГ-ММ-ДДTчч:мм:сс+\-чч:мм
expirationDateTime	String	Срок действия созданной формы для перевода. Формат даты: ГГГГ-ММ-ДДTчч:мм:сс+\-чч:мм
payUrl	String	Ссылка на созданную форму

2. Проверка статуса перевода по счету

Метод позволяет проверить статус перевода по счету. Рекомендуется его использовать после получения уведомления о переводе.

Запрос → GET

URL https://api.qiwi.com/partner/bill/v1/bills/

• billId — уникальный идентификатор счета в вашей системе.

• HEADERS

  • Authorization: Bearer SECRET_KEY
  • Accept: application/json

Ответ ←

Пример тела ответа при ошибке

HEADERS

• Content-Type: application/json

Поле	Тип	Описание
billId	String	Уникальный идентификатор счета в вашей системе, указанный при выставлении
siteId	String	Ваш идентификатор в системе p2p.qiwi
amount	Object	Данные о сумме счета
amount.value	Number	Сумма счета, округленная до 2 знаков после запятой в меньшую сторону.
amount.currency	String	Идентификатор валюты суммы счета (Alpha-3 ISO 4217 код)
status	Object	Данные о статусе счета
status.value	String	Текущий статус счета
status.changedDateTime	String	Дата обновления статуса
customFields	Object	Объект строковых дополнительных параметров, переданных вами
customer	Object	Идентификаторы пользователя
customer.phone	String	Номер телефона (если был указан при выставлении счета)
customer.email	String	E-mail пользователя (если был указан при выставлении счета)
customer.account	String	Идентификатор пользователя в вашей системе (если был указан при выставлении счета)
comment	String	Комментарий к счету
creationDateTime	String	Системная дата создания счета. Формат даты: ГГГГ-ММ-ДДTчч:мм:сс
payUrl	String	Ссылка для переадресации пользователя на созданную форму
expirationDateTime	String	Срок действия созданной формы для перевода. Формат даты: ГГГГ-ММ-ДДTчч:мм:сс+\-чч:мм

3. Отмена неоплаченного счета

Метод позволяет отменить счет, по которому не был выполнен перевод.

Запрос → POST

URL https://api.qiwi.com/partner/bill/v1/bills//reject

Параметры:
• billId — уникальный идентификатор счета в вашей системе.

• HEADERS

  • Authorization: Bearer SECRET_KEY
  • Content-Type: application/json
  • Accept: application/json

Ответ ←

Пример тела ответа при ошибке

HEADERS

• Content-Type: application/json

Поле	Тип	Описание
billId	String	Уникальный идентификатор счета в вашей системе, указанный при выставлении
siteId	String	Ваш идентификатор в p2p.qiwi
amount	Object	Данные о сумме счета
amount.value	Number	Сумма счета, округленная до 2 знаков после запятой в меньшую сторону
amount.currency	String	Идентификатор валюты суммы счета (Alpha-3 ISO 4217 код)
status	Object	Данные о статусе счета
status.value	String	Текущий статус счета
status.changedDateTime	String	Дата обновления статуса. Формат даты: ГГГГ-ММ-ДДTчч:мм:сс+\-чч:мм
customFields	Object	Объект строковых дополнительных параметров. Возможные опции: paySourcesFilter , themeCode
customer	Object	Идентификаторы пользователя. Возможные опции: email , phone , account
comment	String	Комментарий к счету
creationDateTime	String	Системная дата создания счета. Формат даты: ГГГГ-ММ-ДДTчч:мм:сс
payUrl	String	Ссылка на созданную платежную форму
expirationDateTime	String	Срок действия созданной формы для перевода. Формат даты: ГГГГ-ММ-ДДTчч:мм:сс+\-чч:мм

Статусы оплаты счетов

Статус	Описание	Финальный
WAITING	Счет выставлен, ожидает оплаты	—
PAID	Счет оплачен	+
REJECTED	Счет отклонен	+
EXPIRED	Время жизни счета истекло. Счет не оплачен	+

Уведомления о переводе по счету

Адрес сервера для уведомлений указывается в личном кабинете p2p.qiwi.com при генерации ключей.

Перед началом работы с сервисом уведомлений прочитайте условия по интеграции API уведомлений.

Пулы IP-адресов, с которых сервисы QIWI отправляют уведомления:

Если ваш сервер обработки уведомлений работает за брандмауэром, необходимо добавить эти IP-адреса в список разрешенных адресов входящих TCP-пакетов.

Запрос ← POST

Уведомление представляет собой входящий POST-запрос.

Тело запроса содержит JSON-сериализованные данные счета (кодировка UTF-8).

HEADERS

• X-Api-Signature-SHA256: XXX
• Accept: application/json
• Content-type: application/json

Заголовки по стандарту регистронезависимы и ваш клиент может их изменить — смотрите документацию вашего клиента. Если в ответе код состояния HTTP отличается от 200 (OK), это интерпретируется как временная ошибка в вашей системе. Сервер QIWI будет повторять запрос с нарастающим интервалом в течение суток. Обратите внимание, что уведомление может быть отправлено несколько раз даже в случае успешного ответа от вашего сервиса. Вам необходимо учитывать это при разработке бизнес-логики на вашей стороне.

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

После получения входящего уведомления необходимо проверить его подлинность. Для этого используется механизм цифровой подписи. Подпись уведомления отправляется в HTTP заголовке X-Api-Signature-SHA256 . Для формирования подписи используется механизм проверки целостности HMAC с хэш-функцией SHA256.

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

Объединить значения следующих параметров уведомления в одну строку с разделителем | :

где <*>– значение параметра. Все значения при проверке подписи должны трактоваться как строки.

Вычислить HMAC-хэш c алгоритмом хэширования SHA256:

hash = HMAС(SHA256, invoice_parameters, secret_key) Где:

• secret_key – секретный ключ, при помощи которого был выставлен счёт;
• invoice_parameters – строка из п.1;

Сравнить значение заголовка X-Api-Signature-SHA256 с результатом из п.2.

Строка и ключ подписи кодируются в UTF-8.

Данные

В уведомлении содержится информация о счете.

Поле	Описание	Тип
bill	Данные о счете	Object
billId	Уникальный идентификатор счета в вашей системе, указанный при выставлении	String(200)
siteId	Ваш идентификатор в системе p2p.qiwi	String
amount	Данные о сумме счета	Object
amount.value	Сумма счета, округленная до двух десятичных знаков в меньшую сторону	Number(6.2)
amount.currency	Идентификатор валюты суммы счета (Alpha-3 ISO 4217 код)	String(3)
status	Данные о статусе счета	Object
status.value	Строковое значение статуса	String
status.changedDateTime	Дата обновления статуса. Формат даты ГГГГ-ММ-ДДTЧЧ:ММ:ССZ	String
customer	Данные о пользователе	Object
customer.phone	Номер телефона (если был указан при выставлении счета)	String
customer.email	E-mail пользователя (если был указан при выставлении счета)	String
customer.account	Идентификатор пользователя в вашей системе (если был указан при выставлении счета)	String
creationDateTime	Дата создания счета. Формат даты ГГГГ-ММ-ДДTЧЧ:ММ:ССZ	String
expirationDateTime	Срок оплаты счета. Формат даты ГГГГ-ММ-ДДTЧЧ:ММ:СС+ЧЧ:ММ\-Z	String
comment	Комментарий к счету	String(255)
customFields	Дополнительные данные счета (если были указаны при выставлении счета).	Object
version	Версия уведомлений	String

Ответ →

HEADERS

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

Настройки формы и счета

При выставлении счета через API в ответе присутствует поле payUrl со ссылкой на форму. К ссылке можно добавить следующие параметры:

Параметр	Описание	Тип
paySource	При открытии формы сразу будет выбран указанный способ перевода. Возможные значения: qw — QIWI Кошелек card — банковская карта mobile — баланс телефона Если способ перевода недоступен — выбирается рекомендуемый для данного пользователя способ	String
successUrl	URL для переадресации на ваш сайт в случае успешного перевода	URL-Encoded String

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

Пример передачи реферальной ссылки

Для того, чтобы в новых версиях браузеров передавался полный referer при переходе, необходимо выставить дополнительный заголовок Referrer-Policy в ответе сервера. Это можно сделать для всего сайта или отдельно на той странице, где отрисовывается ссылка на форму оплаты. Значение заголовка должно быть no-referrer-when-downgrade .

Персонализация

Вы можете настроить персонализированную форму оплаты – изменить свое имя на название магазина и настроить цвет фона и кнопок.

Перейдите в личном кабинете в раздел Форма приема переводов, нажмите на кнопку Настроить, произведите настройку и нажмите на кнопку Сохранить.

Пример передачи параметра при вызове платежной формы

Пример передачи параметра в запросе к API

При использовании API или SDK вам необходимо будет передавать в параметр customFields переменную themeCode , значение которой у вас отображается в личном кабинете.

Обратите внимание, что значение themeCode индивидуально для разных кошельков.

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

• в случае запроса создания счета добавьте в тело запроса объект customFields c полем
  themeCode и укажите в нем код вашего стиля, например,
  «customFields»: < "themeCode":"кодСтиля">.
• в случае вызова платежной формы добавьте параметр customFields c полем themeCode и укажите в нем код вашего стиля, например, customFields[themeCode]=кодСтиля .

Checkout Popup

Пример работы popup

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

В библиотеке доступно два метода: открытие существующего счета и открытие вашей формы приема переводов.

Установка и подключение:

Открытие существующего счета

Пример открытия уже созданного счета в popup

Параметр	Описание	Тип	Обязательное
payUrl	URL счета	String	+

Открытие персонализированной формы

Пример открытия персонализированной формы

Источник