API интеграции Системы быстрых платежей (СБП) (1.0)
Download OpenAPI specification:Download
Свои предложения и идеи о документации можно оставить в репозитории по адресу: https://github.com/Raiffeisen-DGTL/ecom-API/blob/master/sbp.yaml
Для приема СБП-платежей оставьте заявку на сайте.
Райффайзенбанк выполнит регистрацию. После завершения процесса вы будете оповещены по электронной почте.
Покупатель
- выбирает в ПО партнёра услуги/товары и пункт «Оплата через СБП» (опционально)
- сканирует QR-код, предоставленный партнёром, и подтверждает платеж в приложении своего банка
- получает результат платежа и оплаченные услуги/товары
Партнёр
- запрашивает формирование QR-кода для выбранных товаров/услуг (корзины)
- отображает QR-код клиенту для сканирования и проведения оплаты
- обрабатывает уведомления о результатах СБП-операций
- запрашивает данные по платежу (опционально)
- обеспечивает выдачу товаров/услуг покупателю по факту платежа
Райффайзенбанк
- предоставляет интерфейс для запроса QR-кода со стороны партнёра
- обеспечивает перевод денежных средств на счет партнёра по факту расчетов в СБП
- определяет формат уведомления о факте СБП-платежа
- предоставляет интерфейс для получения данных по платежу
По закону от 22.05.2003 № 54–ФЗ "О применении контрольно-кассовой техники при осуществлении расчетов в Российской Федерации" при оплате товаров, работ или услуг необходимо формировать фискальный чек и отправлять его в налоговую с помощью кассы.
Райффайзенбанк предоставляет возможность фискализировать чеки через API банка.
На схеме ниже представлен сценарий работы с кассовой ссылкой СБП. Здесь и далее для ее обозначения используется тип QRVariable. Это тип QR-кода, который означает кассовую ссылку СБП и на уровне API и хранения данных отличает ее от статического и динамического QR-кодов.
B случае если прием платежей планируется на сайте или в мобильном приложении, рекомендуем использовать протокол с отображением QR-кода на нашей форме.
Если прием платежей реализуется в физических точках или по каким-либо причинам вам не подходит решение с нашей формой, можете использовать протокол, описанный ниже.
Вы можете предложить клиенту привязать оплату по СБП к программе лояльности или к аккаунту в вашем сервисе. Для этого вы можете сгенерировать QR-код и отобразить его клиенту либо перенаправить его на специальную ссылку, которая есть в ответе на запрос генерации QR-кода на подписку.
После по уникальному идентификатору подписки вы можете обращаться за безакцептным списанием средств с клиента за ваши товары и услуги.
Также есть схема, когда одним запросом создается QR-код на получение оплаты и заведение подписки.
В данном случае клиент проводит оплату, после чего ему отображается окно с предложением подключения подписки.
Клиент может провести оплату, но отказаться от подписки. Также клиент может провести оплату из приложения банка, который не подключен к сервису подписок.
Bзаимодействие осуществляется по протоколу HTTP с использованием методов GET/POST/DELETE (в описании каждого запроса явно указан требуемый метод и адрес).
POST-запрос использует JSON-аргументы, GET и DELETE-запросы работают со строками запросов.
API всегда возвращает ответ в формате JSON, независимо от типа запроса.
Стандартный ответ сервиса содержит код сообщения (code). Если в процессе обработки запроса произойдет логическая ошибка, API вернет описание ошибки (message).
Запросы, связанные с получением данных по платежу и управлением платежами, авторизуются посредством секретного ключа API (secretKey). Параметр авторизации указывается в заголовке Authorization, значение которого формируется как "Bearer secretKey".
Для получения тестовых данных для интеграции необходимо заполнить анкету на pay.raif.ru.
Посмотреть боевой sbpMerchantId и сгенерировать ключи можно в личном кабинете во вкладке "Прием платежей".
Секретный ключ необходимо хранить в доверенной среде, так как по нему возможно проведение возвратов.
Мы рекомендуем создавать одного мерчанта на ЮЛ и, соответственно, все его торговые точки. Это избавит от необходимости:
- хранить справочник мерчантов с соотношением с вашими торговыми точками
- хранить большое количество секретных ключей и проводить их индивидуальную настройку для каждой торговой точки по отдельности
- регистрировать новых мерчантов при открытии новых торговых точек ЮЛ
- проводить возвраты только в той торговой точке, где была произведена оплата
- строить сложную отчетность по разным мерчантам
- распределять QR по разным мерчантам (в случае работы с QRVariable)
При работе в мобильной версии сайта или приложении мы рекомендуем использовать нашу форму.
Если планируете использовать свою форму, то необходимо реализовать виджет выбора банка, для этого нужно для каждого банка получить его схему:
И подставить ее в url из параметра payload взамен https.
Для корректной работы выбора банка, рекомендуем использовать виджет от НСПК: IOS, Android, WEB - https://sbp.nspk.ru/business_online/#widget-business
Или вы можете воспользоваться нашими SDK: Android - https://github.com/Raiffeisen-DGTL/sbp-sdk-android IOS - https://github.com/Raiffeisen-DGTL/payform-sdk-ios
Для работы с СБП через NFC необходимо реализовать взаимодействие через "кассовую платежную ссылку".
Необходимо на каждую кассу сгенерировать QR c типом QRVariable. Из ответа на запрос генерации QR, нужно получить ссылку из параметра payload, в ссылке в начало домена необходимо добавить "web." и полученную ссылку нужно зашить в NFC метку.
Пример:
В payload вы получили https://qr.nspk.ru/AS100004BAL7227F9BNP6KNE007J9B3K?type=01&bank=100000000007,
в NFC метку нужно будет зашить https://web.qr.nspk.ru/AS100004BAL7227F9BNP6KNE007J9B3K?type=01&bank=100000000007
Для полного цикла тестирования оплаты Райффайзенбанк предоставляет возможность использования демо-приложения для сканирования QR-кода от имени покупателя по адресу: https://pay.raif.ru/pay/rfuture/
Указанный адрес можно открыть в браузере любого устройства, где есть камера. Никакого дополнительного софта/плагинов устанавливать не нужно. Далее нажать на значок СБП (при необходимости разрешить браузеру доступ к камере) и поднести к ней изображение QR-кода. Если камера не открылась, проверьте, что в адресе указан протокол HTTPS.
Регистрация QR-кода выполяется без авторизации, что позволяет сгенерировать его на сайте или приложении.
Регистрация QR
Метод позволяет генерировать статические QR-коды, динамические QR-коды и кассовую ссылку СБП (QRVariable) для каждой кассы. Также с помощью данного метода вы можете сгенерировать QR-код для оплаты с подпиской.
При каждом новом запросе будет возвращаться новый QR.
Тестовые QR можно оплатить только с помощью тестового приложения.
Request Body schema: application/json
| qrType required | string Тип QR-кода QRDynamic QRDynamic QRStatic QRVariable |
| account | number <= 20 Счет для зачисления. Параметр используется, если необходимо разносить платежи на разные счета |
| additionalInfo | string <= 140 characters Дополнительная информация. Может быть доступна для пользователя в зависимости от банка, назначение платежа плательщика.
Поподает в реестр в колонку "Комментарий"
Не может быть пустым или содержать только пробелы. Может содержать: |
| amount required | number Сумма в рублях |
| currency | string 3 characters Value: "RUB" Валюта платежа. Если не заполнено, то автоматически указывается значение RUB |
| order required | string [ 1 .. 40 ] characters ^[A-z0-9-_.] Уникальный идентификатор заказа в системе партнёра. Рекомендуем использовать длинный формат без возможности перебора, например, использовать формат UUID v4 |
| paymentDetails | string <= 185 characters Назначение платежа в выписке получателя. |
| qrExpirationDate | string <YYYY-MM-DD ТHH24:MM:SS±HH:MM / +nM / +nm> non-empty Срок действия QR-кода |
| sbpMerchantId required | string <= 12 characters Идентификатор зарегистрированного партнёра в СБП |
object Используется для оплаты с последующей подпиской | |
| redirectUrl | string <uri> Ссылка для автоматического возврата плательщика из приложения банка в приложение или на сайт магазина. Ссылка должна содержать https:// для web страниц или уникальную схему для мобильного приложения |
| qrDescription | string <= 32 characters Описание QR-кода |
object Дополнительные поля для свободного заполнения по принципу key-value |
Responses
Response Schema: application/json
| qrId | string <= 32 characters Уникальный идентификатор QR |
| qrStatus | string Enum: "INACTIVE" "NEW" "IN_PROGRESS" "PAID" "EXPIRED" "CANCELLED" Статус QR-кода |
| qrExpirationDate | string <YYYY-MM-DD ТHH24:MM:SS±HH:MM> Опциональный параметр для указания срока действия QR-кода. После истечения срока действия QR-кода оплату по нему провести нельзя |
| payload | string Данные для самостоятельной генерации изображения зарегистрированного QR-кода в СБП. При открытии с мобильного устройства запускает банковское приложение клиента или список для выбора банка |
| qrUrl | string URL с изображением зарегистрированного QR-кода |
| subscriptionId | string Идентификатор подписки |
Request samples
- Payload
- cURL
{- "account": 40700000000000000000,
- "additionalInfo": "Доп. информация",
- "amount": 1110.11,
- "currency": "RUB",
- "order": "1-22-333",
- "paymentDetails": "Назначение платежа",
- "qrType": "QRDynamic",
- "extra": {
- "apiClient": "iiko",
- "apiClientVersion": "1.0.0"
}, - "qrExpirationDate": "2023-07-22T09:14:38+03:00",
- "sbpMerchantId": "MA0000000552",
- "qrDescription": "QR для оплаты заказа"
}Response samples
- 200
- 400
- 415
{- "qrId": "AD1F2CD7212E48FA919AB52EF0AEFB33",
- "qrStatus": "NEW",
- "subscriptionId": "120059"
}Регистрация QR Deprecated
Метод позволяет генерировать как статические QR-коды, так и динамические QR-коды. Также с помощью данного метода вы можете сгенерировать QR-код для оплаты с подпиской.
Тестовые QR можно оплатить только нашим тестовым приложением.
Request Body schema: application/json
| qrType required | string Тип QR-кода QRDynamic QRDynamic QRStatic |
| account | number <= 20 Счет для зачисления. Параметр используется, если необходимо разносить платежи на разные счета |
| additionalInfo | string <= 140 characters Дополнительная информация. Может быть доступна для пользователя в зависимости от банка, назначение платежа плательщика.
Поподает в реестр в колонку "Комментарий"
Не может быть пустым или содержать только пробелы. Может содержать: |
| amount required | number Сумма в рублях |
| currency | string 3 characters Value: "RUB" Валюта платежа. Если не заполнено, то автоматически указывается значение RUB |
| order required | string [ 1 .. 40 ] characters ^[A-z0-9-_.] Уникальный идентификатор заказа в системе партнёра. Рекомендуем использовать длинный формат без возможности перебора, например, использовать формат UUID v4 |
| paymentDetails | string <= 185 characters Назначение платежа в выписке получателя. |
| qrExpirationDate | string <YYYY-MM-DD ТHH24:MM:SS±HH:MM / +nM / +nm> non-empty Срок действия QR-кода |
| sbpMerchantId required | string <= 12 characters Идентификатор зарегистрированного партнёра в СБП |
object Используется для оплаты с последующей подпиской | |
| redirectUrl | string <uri> Ссылка для автоматического возврата плательщика из приложения банка в приложение или на сайт магазина. Ссылка должна содержать https:// для web страниц или уникальную схему для мобильного приложения |
| qrDescription | string <= 32 characters Описание QR-кода |
object Дополнительные поля для свободного заполнения по принципу key-value |
Responses
Response Schema: application/json
| code | string <= 140 characters Код сообщения |
| qrId required | string <= 32 characters Идентификатор зарегистрированного QRС в СБП |
| payload required | string Данные для самостоятельной генерации изображения зарегистрированного QR-кода в СБП. При открытии с мобильного устройства запускает банковское приложение клиента или список выбора банка |
| qrUrl required | string URL с изображением зарегистрированного QR-кода в СБП |
| subscriptionId | string Идентификатор подписки |
Request samples
- Payload
- cURL
- Java
{- "account": 40700000000000000000,
- "additionalInfo": "Доп. информация",
- "amount": 1110.11,
- "currency": "RUB",
- "order": "1-22-333",
- "paymentDetails": "Назначение платежа",
- "qrType": "QRDynamic",
- "qrExpirationDate": "2023-07-22T09:14:38+03:00",
- "sbpMerchantId": "MA0000000552"
}Response samples
- 200
- 415
{- "code": "SUCCESS",
- "qrId": "AD1F2CD7212E48FA919AB52EF0AEFB33",
- "subscriptionId": "120059"
}Отмена QR
Метод позволяет отменить ранее созданный QR. QRDynamic можно отменить только до момента его оплаты. Для QRVariable отменяет последний активный заказ, до момента его оплаты.
path Parameters
| qrId required | string Уникальный идентификатор QR |
header Parameters
| Authorization required | string |
Responses
Request samples
- cURL
curl --location --request DELETE 'https://pay-test.raif.ru/api/sbp/v2/qrs/ADAC306DDBF443CA94EBE3FA85CA4872' \ --header 'Authorization: Bearer eyJ0eXA***'
Для реализации взаимодействия с партнёром Райффайзенбанк предоставляет API из следующих запросов:
- отмена QR-кода,
- получение данных по зарегистрированному QR-коду,
- получение данных по платежу,
- возврат денежных средств - может быть выполнен в любое время после проведения оплаты на полную сумму платежа или частичную. Однако сумма частичных запросов на возврат не должна превышать общую сумму заказа.
- получение информации по возврату.
Получение данных по зарегистрированному QR
Метод позволяет получить данные по зарегистрированному ранее QR-коду
path Parameters
| qrId required | string Уникальный идентификатор QR |
header Parameters
| Authorization required | string |
Responses
Response Schema: application/json
| qrId required | string Идентификатор зарегистрированного QR в СБП |
| qrStatus required | string Enum: "NEW" "IN_PROGRESS" "CANCELLED" "EXPIRED" "PAID" Код состояния QR-кода |
| qrExpirationDate required | string Опциональный параметр для указания срока действия QR-кода. При заполнении не может быть меньше текущей даты и времени. После истечения срока действия QR-кода оплату по нему провести нельзя. Если Тип QR = QRDynamic и поле не заполнено, срок действия будет 3 суток. ISO 8601 |
| payload required | string Данные для самостоятельной генерации изображения зарегистрированного QR-кода в СБП. При открытии с мобильного устройства, запускает банковское приложение клиента или список выбора банка |
| qrUrl required | string URL с изображением зарегистрированного QR-кода в СБП |
| subscriptionId | string Идентификатор подписки |
Request samples
- cURL
curl --location --request GET 'https://pay-test.raif.ru/api/sbp/v2/qrs/ADAC306DDBF443CA94EBE3FA85CA4872' \ --header 'Authorization: Bearer eyJ0eXA***'
Response samples
- 200
{- "qrId": "AD100004BAL7227F9BNP6KNE007J9B3K",
- "qrStatus": "NEW",
- "qrExpirationDate": "2023-07-22T09:14:38+03:00",
}Получение данных по зарегистрированному QR Deprecated
Метод позволяет получить данные по зарегистрированному ранее QR-коду
path Parameters
| qrId required | string Уникальный идентификатор QR |
header Parameters
| Authorization required | string |
Responses
Response Schema: application/json
| code | string <= 140 characters Код сообщения |
| qrId required | string <= 32 characters Идентификатор зарегистрированного QRС в СБП |
| payload required | string Данные для самостоятельной генерации изображения зарегистрированного QR-кода в СБП. При открытии с мобильного устройства запускает банковское приложение клиента или список выбора банка |
| qrUrl required | string URL с изображением зарегистрированного QR-кода в СБП |
| subscriptionId | string Идентификатор подписки |
Request samples
- cURL
- Java
curl --location --request GET 'https://pay-test.raif.ru/api/sbp/v1/qr/AS6E5A7F9E3A4E648C536EC930AECDF6/info' \ --header