Через СБП по номеру телефона · Documentation

Начало работы

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

Get →

Выставление счета с передачей суммы платежа

Yandex pay

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

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

Авторизация

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

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

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

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

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

Возвраты и отмены

Операции возврата и отмены доступны не для всех способов платежей:

При возврате платежа комиссия QIWI за проведение платежа не возвращается. Исключение — если при возврате платежа выполнена операция отмены. В этом случае финансовой операции (списания средств со счета покупателя) не происходит и комиссия не взимается.

Возвраты по проведенным платежам

Возврат по платежу возможен только для успешно проведенного платежа. Возврат может быть как частичным, так и полным. В первом случае возвращается вся сумма принятого платежа. Во втором — только часть от суммы платежа. Перед возвратом платежа проверьте, что платеж успешно завершен и находится в статусе COMPLETED.

Чтобы выполнить возврат по платежу, используйте метод API Операция возврата.

Чтобы выполнить возврат по платежу через СБП, используйте метод API Операция возврата по платежу СБП.

Возвраты по сплитованным платежам

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

Пример запроса

Возвращает

В случае успеха возвращает JSON-документ со следующим содержимым:

Возмещение

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

КИВИ взимает комиссию за каждую подтвержденную операцию. Если отмена операции была произведена до подтверждения, комиссия не взимается. Если была произведена частичная отмена до подтверждения операции, комиссия будет пересчитана.

Выпуск платежного токена qiwi кошелька

Пример запроса с инициацией выпуска платежного токена QIWI Кошелька

Выпуск платежного токена карты

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

Выпуск токена для оплаты через сбп

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

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

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

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

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

** — посредством выпуска платежного токена для КИВИ кошелька.

Интеграция c платежной формой qiwi без использования api

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

Для вызова формы в ссылке необходимо указывать ключ PUBLIC_KEY. Для каждого siteId выпускается уникальный ключ. Ключ можно посмотреть в Личном кабинете в разделе Настройки.

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

По умолчанию сервис QIWI ожидает подтверждения платежа в течение 72 часов. По истечении срока выполняется автоматическое подтверждение платежа.

Интеграция с платежной формой qiwi

Чтобы отправить платеж со сплитованием, передайте в запросе API Создание счета массивsplits c данными поставщиков.

Интеграция с платежной формой мерчанта

Чтобы отправить платеж со сплитованием, передайте в запросе API Платеж JSON-массив paymentSplits с данными поставщиков.

Использование

Для использования SDK необходимо создать объект класса SbpClient, указав в конструкторе URL, на который будут отправляться запросы (SbpClient.PRODUCTION_URL или SbpClient.TEST_URL), id мерчанта в системе СБП и секретный ключ для авторизации.
Этот клиент используется для всех взаимодействий с API.

Все запросы осуществляются классом SbpClient. Посмотреть возвращаемые значения можно по ссылке.

Клиент может вернуть следующие типы исключений:

• IOException – ошибка сетевого взаимодействия
• SbpException – логическая ошибка при попытке обработать запрос
• ContractViolationException – ошибка в обработке ответа от сервера

Как использовать сервис через api

Пример запроса проверки карты

Как использовать сервис через платежную форму qiwi

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

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

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

Как подключить сервис быстрых платежей для интернет-магазина

Как провести выплату

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

Посмотреть сценарий выплат

Назначение документа raiffeisenbank e-commerce api

Это инструмент для интеграции с эквайрингом Райффайзенбанка — для разработчиков. Позволяет принимать платежи и узнавать об их статусе. В этом документе собраны описания основных сценариев с примерами кода, а также вся информация о структуре запросов, объектах и переменных .

Назначение документа сбп api raiffeisenbank

Это инструмент для интеграции с системой быстрых платежей Райффайзенбанка — для разработчиков. Позволяет регистрировать QR-коды для C2B платежей, получать данные о зарегистрированном QR-коде, узнавать информацию по платежу, а также настроить уведомления о статусе платежа.

Назначение документа сбп payout api raiffeisenbank

Это инструмент для интеграции с системой быстрых платежей Райффайзенбанка — для разработчиков. Позволяет проводить выплаты, опрашиваиь статус операций, настроить сервис callback’ов . Помимо основной информации о схеме работы СБП B2C Райффайзенбанка и контактной информаци, документ содержит в себе описания базовых сценариев с примерами кода. Вся информация о структуре запросов, объектах и переменных также находится в протоколе.

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

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

• Банковские карты Visa, Mastercard, МИР.
• Yandex Pay.
• QIWI Кошелек.
• Система Быстрых Платежей (СБП).
• Баланс мобильного телефона.

Обработка уведомлений

Для хранения и использования уведомлений существует класс PaymentNotification, экземпляр которого можно получить с помощью статического метода SbpUtil.parseJson(String).

Для проверки подлинности уведомления существуют перегруженные статические методы SbpUtil.checkNotificationSignature. Примеры использования:

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

sequenceDiagram
participant customer as Покупатель
participant store as Магазин мерчанта
participant ipsstore as Кредитная организация мерчанта
participant qb as QIWI
participant ips as Платежная система
participant ipscust as Кредитная организация Покупателя Эмитент или банк-отправитель
customer->>store:

Старт оплаты
store->>qb:Платеж
qb->>ips:Авторизация платежа
ips->>ipscust:Авторизация платежа
rect rgb(237, 243, 255)
Note over ipsstore, ipscust:Взаиморасчеты
ipscust->>ips:₽₽₽
ips->>qb:₽₽₽
qb->>ipsstore:₽₽₽
end

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

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

Оплата картой в тестовом режиме

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

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

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

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

Оплата токеном через сбп

Пример тела запроса

Оплата через сбп

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

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

Оплата через сбп в тестовом режиме

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

Особенности

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

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

Оформление возврата по платежу

Для возврата средств необходимо создать объект класса RefundInfo, заполнив необходимые поля, и вызвать метод refundPayment(RefundInfo). Подробности об обязательных полях в документации.

Обязательные параметры:

• сумма возврата в рублях amount(BigDecimal)
• идентификатор заказа платежа в Райффайзенбанке, используется для возвратов по динамическому QR order(String)
• уникальный идентификатор запроса на возвратrefundId(String)

Ответ:

Параметры

В URL указываются параметры счета.

Передача чека (54-фз)

Для работы по 54-ФЗ Протокол приема платежей предоставляет инструмент для взаимодействия с вашей онлайн-кассой. Информация для формирования фискального чека передается в JSON-объекте cheque в операциях API выставления счета и платежа.

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

Если используется Атол, то дополнительно предоставьте сведения:

• email ТСП для печати в чеке;
• полное название организации;
• реквизиты ОФД (название, ИНН, url);
• login и password для генерации токена;
• код группы.

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

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

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

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

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

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

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

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

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

Подключение

Требования:

Для подключения SDK требуется:

• Выполнить команды в maven:
  • validate(mvn validate)
  • install(mvn install)

Получение данных

Описание операций описано по ссылке:

Получение данных по зарегистрированному ранее qr-коду

Необходимо создать объект класса QRId, передав в конструкторе идентификатор QR-кода, и вызвать метод getQRInfo(QRId):

Ответ

Получение информации по возврату

Для выполнения данного запроса необходимо указать уникальный идентификатор запроса на возврат refundId при вызове метода getRefundInfo(refundId):

Ответ:

Получение информации по платежу

Необходимо создать объект класса QRId, передав в конструкторе идентификатор QR-кода, и вызвать метод getPaymentInfo(QRId):

Ответ:

{
  "additionalInfo": "Доп информация",
  "amount": 12399,
  "createDate": "2020-01-31T09:14:38.107227 03:00",
  "currency": "RUB",
  "merchantId": 123,
  "order": "282a60f8-dd75-4286-bde0-af321dd081b3",
  "paymentStatus": "NO_INFO",
  "qrId": "AD100051KNSNR64I98CRUJUASC9M72QT",
  "sbpMerchantId": "MA0000000553",
  "transactionDate": "2022-07-11T17:45:13.109227 03:00",
  "transactionId": 23
}

Получение списка точек продаж

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

Пример ответа (json)

 [
	{
		"id": "51d693fb-c7f7-48c4-911f-65055203a533",
		"name": "Торговая точка СБП",
		"phone": "3221110189",
		"сity": "Уфа",
		"zip": "450076",
		"address": "г. Уфа, ул. ул Аксакова, 4",
		"type": "QRPay",
		"created": "2021-03-18T03:37:27.036396",
		"hasStaticQrCode": true,
		"binded": false,
		"activationCode": "A79EC1DE",
		"merchantCategoryCode": {
			"code": "5411",
			"name": "Бакалейные магазины, Супермаркеты",
			"category": "Супермаркеты"
		},
		"bankAccount": "40802810570010294158",
		"status": "Registered"
	}
]

Проверка карты покупателя

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

Если проверка пройдена успешно, для карты может быть выпущен платежный токен.

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

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

sequenceDiagram
participant customer as Покупатель
participant store as Магазин
participant qb as QIWI (эквайер)
participant ips as Эмитент
customer->>store:Выбор товаров, Старт оплаты,ввод платежных данных
activate store
store->>qb:

ПлатежОдношаговый платеж — все способы оплатыДвухшаговый платеж — только карты
activate qb
qb->>store:Статус операции, данные для 3DS или QR-код СБП
rect rgb(237, 243, 255)
Note over customer, ips:3-D Secure
store->>customer:

Переадресация покупателя на acsUrl или в приложение банка
activate ips
ips->>customer:Аутентификация покупателя:3DS — карты,СБП — подтверждение операции в интерфейсе эмитента карты
customer->>ips:Аутентификация
ips->>store:

Результат аутентификации (PaRes)
store->>qb:Завершение аутентификации (complete)
end
qb->>ips:Запрос списания денежных средств
activate ips
ips->>qb:Статус операции
qb->>store:Уведомление о статусе операции
rect rgb(237, 243, 255)

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

• ключ API;
• сумму платежа;
• метод платежа;
• другую информацию для создания платежа.

Регистрация qr-кода

Для регистрации кода необходимо создать экземпляр класса QRStatic или QRDynamic. Для разных типов QR-кодов обязательные параметры отличаются.

Обязательные параметры:

• номер заказа в системе партнера order(String)
• (QRDynamic) сумма в рублях amount(BigDecimal)

Опциональные параметры могут быть заполнены с помощью set методов.

Для выполнения запроса необходимо вызвать соответствующий метод класса SbpClient, принимающий в качестве аргумента объект класса QR:

Ответ:

Пример с минимальными данными:

Также существует возможность заполнить необязательный параметр qrExpirationDate с помощью сдвига относительно даты создания. Для этого в поле qrExpirationDate следует указать строку вида ” <число1><буква1>”.

• ‘M’ – месяц
• ‘d’ – день
• ‘H’ – час
• ‘m’ – минута
• ‘s’ – секунда

Пример:

Реестры

Реестр операций отправляется после 14:00 МСК по рабочим дням, содержит информацию только об успешных платежах, обработанных банком. Реестр полностью соответствует Акту.

Реестр отправляется на email, указанный при регистрации в сервисе, во вложенном в письме zip-архиве.

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

Пример уведомления

Система быстрых платежей как альтернатива applepay и gpay в онлайне — личный опыт на

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

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

Сплитование платежей

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

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

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

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

Справочник ошибок api

Ошибки API описывают причину отклонения операции и передаются:

• в ответах на запросы — в поле status.reason;
• в уведомлениях — в поле status.reasonCode.

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

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

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

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

Статусы операций

Статус операции отражает ее текущее состояние.

API возвращает синхронный статус операции в поле status.value.

В уведомлениях статус помещается в поле {operation}.status.value.

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

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

Ключ доступа к API — Символьная строка для авторизации мерчанта в API согласно стандарту OAuth 2.0 RFC 6749RFC 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.

Тестовый режим

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

Для тестирования операций оплаты используются URL протокола.

Тестовый режим для метода оплаты с баланса КИВИ Кошелька не предусмотрен.

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

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

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

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

• Счет (Invoice) — электронный документ, выставляемый продавцом покупателю. Содержит информацию о сумме и номере заказа. Не является финансовой сущностью и имеет ограниченный срок жизни. Выставление счета необходимо для получения ссылки на платежную форму QIWI.
• Платеж (Payment) — операция списания денежных средств от покупателя в пользу продавца. Фактическое списание происходит только после подтверждения (Capture). При работе через платежную форму QIWI, Payment — попытка оплаты счета (Invoice).
• Завершение (Complete) — завершение 3DS-верификации Покупателя. Используется при работе через Платежную форму мерчанта.
• Подтверждение (Capture) — операция подтверждения авторизации (списания) средств.
• Возврат (Refund) — возврат средств покупателю по успешному платежу. Финансовая операция списания денежных средств от продавца в пользу покупателя. Если подтверждения операции Payment не было, то в ответе на операцию Refund вы получите флаг Reversal и деньги со счета Покупателя на счет продавца не перечислятся (комиссия за эквайринг также не удерживается).

Уведомления по сплитованным операциям

Пример уведомления по сплитованным платежам

Удаление платежного токена

Удаление платежного токена

Формат взаимодействия

API Протокола приема платежей основано на принципах REST-архитектуры.

Формат реестра

Пример фрагмента реестра

Формат уведомления capture

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

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

• 1 попытка с отложенным временем 5 секунд
• 1 попытка с отложенным временем 1 минута
• 3 попытки с отложенным временем по 5 минут

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

Шпаргалка