API интеграции Системы быстрых платежей (СБП) (1.0)

Download OpenAPI specification:Download

Support e-mail: ecom@raiffeisen.ru

Свои предложения и идеи о документации можно оставить в репозитории по адресу: https://github.com/Raiffeisen-DGTL/ecom-API/blob/master/sbp.yaml

Подключение к СБП

Для приема СБП-платежей оставьте заявку на сайте.

Райффайзенбанк выполнит регистрацию. После завершения процесса вы будете оповещены по электронной почте.

Участники СБП

Покупатель

  • выбирает в ПО партнёра услуги/товары и пункт «Оплата через СБП» (опционально)
  • сканирует QR-код, предоставленный партнёром, и подтверждает платеж в приложении своего банка
  • получает результат платежа и оплаченные услуги/товары

Партнёр

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

Райффайзенбанк

  • предоставляет интерфейс для запроса QR-кода со стороны партнёра
  • обеспечивает перевод денежных средств на счет партнёра по факту расчетов в СБП
  • определяет формат уведомления о факте СБП-платежа
  • предоставляет интерфейс для получения данных по платежу

Поддержка 54-ФЗ

По закону от 22.05.2003 № 54–ФЗ "О применении контрольно-кассовой техники при осуществлении расчетов в Российской Федерации" при оплате товаров, работ или услуг необходимо формировать фискальный чек и отправлять его в налоговую с помощью кассы.

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

Общие схемы работы

Кассовая ссылка для торговых точек

На схеме ниже представлен сценарий работы с кассовой ссылкой СБП. Здесь и далее для ее обозначения используется тип QRVariable. Это тип QR-кода, который означает кассовую ссылку СБП и на уровне API и хранения данных отличает ее от статического и динамического QR-кодов.

Платежная форма для сайта

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

Динамический QR Whitelabel

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

Подписки

Вы можете предложить клиенту привязать оплату по СБП к программе лояльности или к аккаунту в вашем сервисе. Для этого вы можете сгенерировать QR-код и отобразить его клиенту либо перенаправить его на специальную ссылку, которая есть в ответе на запрос генерации QR-кода на подписку.

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

Подписки с оплатой

Также есть схема, когда одним запросом создается QR-код на получение оплаты и заведение подписки.

В данном случае клиент проводит оплату, после чего ему отображается окно с предложением подключения подписки.

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

Подписки с автоматическим списанием

Механизм подписок также поддерживает регулярные автоматические списания, которые банк проводит в указанную дату в 10:00 или 13:00 по московскому времени. На данный момент поддерживаются только ежемесячные списания. При неуспешной оплате в 10:00 производится еще одна попытка в 13:00 того же дня, при повторной ошибке будет еще по две попытки в последующие дни в то же время. Неуспешность платежа не ведет к отмене подписки.

Автоматические списания возможны как для оплаты с последующей подпиской, так и для подписки без оплаты в этот момент. Для автоматических платежей необходимо передать дополнительные параметры списания в методе создания QR или методе создания подписки.

Сообщения о платежах можно получать в виде callback-уведомлений. В теле сообщения в объекте extra будет приходить ключ, переданный ранее при создании подписки или QR. Деактивировать подписку можно методом отмены подписки.

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

Для более быстрой интеграции вы можете воспользоваться нашими SDK:

Также список готовых решений вы можете посмотреть по ссылке.

Описание API

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 и СБПэй

Для работы с СБП через 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

Метод позволяет генерировать статические QR-коды, динамические QR-коды и кассовую ссылку СБП (QRVariable) для каждой кассы. Также с помощью данного метода вы можете сгенерировать QR-код для оплаты с подпиской.

При каждом новом запросе будет возвращаться новый QR.

Тестовые QR можно оплатить только с помощью тестового приложения.

Request Body schema: application/json
qrType
required
string

Тип QR-кода
Динамический QR-код создается под каждую продажу. Такой QR можно оплатить только один раз, сумма зашивается сразу в QR

account
number <= 20

Счет для зачисления. Параметр используется, если необходимо разносить платежи на разные счета

additionalInfo
string <= 140 characters

Дополнительная информация. Может быть доступна для пользователя в зависимости от банка, назначение платежа плательщика. Попадает в реестр в колонку "Комментарий" Не может быть пустым или содержать только пробелы. Может содержать:
• Символы латинского алфавита (A–Z и a–z) с десятичными кодами из диапазонов [065-090] и [097-122] в кодировке UTF-8;
• Символы русского алфавита (А-Я и а-я) с десятичными кодами из диапазона [1040-1103] в кодировке UTF-8;
• Цифры 0-9 с десятичными кодами из диапазона [048-057] в кодировке UTF-8;
• Специальные символы с десятичными кодами из диапазонов [032-047], [058-064], [091-096], [123-126] в кодировке UTF-8; - Символ «№» под номером 8470 в кодировке UTF-8

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-кода
Может содержать точную дату и время или количество минут. Передача срока в минутах удобна для торговых точек, которые не привязываются к точному времени или часовому поясу
Параметр не может быть меньше текущей даты и времени. Если указывается в минутах, то не может быть меньше 1 минуты. Максимальное значение - 90 суток. Если параметр не передан, то по умолчанию QR будет действителен 3 суток
После истечения срока действия QR-кода оплату по нему провести нельзя

sbpMerchantId
required
string <= 12 characters

Идентификатор зарегистрированного партнёра в СБП

redirectUrl
string <uri>

Ссылка для автоматического возврата плательщика из приложения банка в приложение или на сайт магазина. Ссылка должна содержать https:// для web страниц или уникальную схему для мобильного приложения

qrDescription
string <= 32 characters

Описание QR-кода
Может содержать любую информацию для удобства идентификации конкретного QR-кода. Например, его местоположение или расположение в магазине. Отображается в ЛК и RBO. Не отображается покупателю и в выписке

object

Используется для оплаты с последующей подпиской

object

Дополнительные поля для свободного заполнения по принципу key-value

Responses

Response Schema: application/json
qrId
string <= 32 characters

Уникальный идентификатор QR

qrStatus
string
Enum: "INACTIVE" "NEW" "IN_PROGRESS" "PAID" "EXPIRED" "CANCELLED"

Статус QR-кода
Статус NEW означает готовность к оплате. QR-код с типом QRStatic или QRDynamic создается в статусе NEW, QRVariable - в статусе INACTIVE

qrExpirationDate
string <YYYY-MM-DD ТHH24:MM:SS±HH:MM>

Опциональный параметр для указания срока действия QR-кода. После истечения срока действия QR-кода оплату по нему провести нельзя

payload
string

Данные для самостоятельной генерации изображения зарегистрированного QR-кода в СБП. При открытии с мобильного устройства запускает банковское приложение клиента или список для выбора банка

qrUrl
string

URL с изображением зарегистрированного QR-кода

subscriptionId
string

Идентификатор подписки

Request samples

Content type
application/json
Example
{
  • "account": 40700000000000000000,
  • "additionalInfo": "Доп. информация",
  • "amount": 1110.11,
  • "currency": "RUB",
  • "order": "1-22-333",
  • "paymentDetails": "Назначение платежа",
  • "qrType": "QRDynamic",
  • "extra": {
    • "extraParam": "Example extra param"
    },
  • "qrExpirationDate": "2023-07-22T09:14:38+03:00",
  • "sbpMerchantId": "MA0000000552",
  • "redirectUrl": "https://bfkh.ru/",
  • "qrDescription": "QR для оплаты заказа"
}

Response samples

Content type
application/json
Example

Регистрация QR Deprecated

Метод позволяет генерировать как статические QR-коды, так и динамические QR-коды. Также с помощью данного метода вы можете сгенерировать QR-код для оплаты с подпиской.

Тестовые QR можно оплатить только нашим тестовым приложением.

Request Body schema: application/json
qrType
required
string

Тип QR-кода
Динамический QR-код создается под каждую продажу. Такой QR можно оплатить только один раз, сумма зашивается сразу в QR

account
number <= 20

Счет для зачисления. Параметр используется, если необходимо разносить платежи на разные счета

additionalInfo
string <= 140 characters

Дополнительная информация. Может быть доступна для пользователя в зависимости от банка, назначение платежа плательщика. Попадает в реестр в колонку "Комментарий" Не может быть пустым или содержать только пробелы. Может содержать:
• Символы латинского алфавита (A–Z и a–z) с десятичными кодами из диапазонов [065-090] и [097-122] в кодировке UTF-8;
• Символы русского алфавита (А-Я и а-я) с десятичными кодами из диапазона [1040-1103] в кодировке UTF-8;
• Цифры 0-9 с десятичными кодами из диапазона [048-057] в кодировке UTF-8;
• Специальные символы с десятичными кодами из диапазонов [032-047], [058-064], [091-096], [123-126] в кодировке UTF-8; - Символ «№» под номером 8470 в кодировке UTF-8

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-кода
Может содержать точную дату и время или количество минут. Передача срока в минутах удобна для торговых точек, которые не привязываются к точному времени или часовому поясу
Параметр не может быть меньше текущей даты и времени. Если указывается в минутах, то не может быть меньше 1 минуты. Максимальное значение - 90 суток. Если параметр не передан, то по умолчанию QR будет действителен 3 суток
После истечения срока действия QR-кода оплату по нему провести нельзя

sbpMerchantId
required
string <= 12 characters

Идентификатор зарегистрированного партнёра в СБП

redirectUrl
string <uri>

Ссылка для автоматического возврата плательщика из приложения банка в приложение или на сайт магазина. Ссылка должна содержать https:// для web страниц или уникальную схему для мобильного приложения

qrDescription
string <= 32 characters

Описание QR-кода
Может содержать любую информацию для удобства идентификации конкретного QR-кода. Например, его местоположение или расположение в магазине. Отображается в ЛК и RBO. Не отображается покупателю и в выписке

object

Используется для оплаты с последующей подпиской

object

Дополнительные поля для свободного заполнения по принципу key-value

Responses

Response Schema: application/json
code
string <= 140 characters

Код сообщения

qrId
string <= 32 characters

Идентификатор зарегистрированного QRС в СБП

payload
string

Данные для самостоятельной генерации изображения зарегистрированного QR-кода в СБП. При открытии с мобильного устройства запускает банковское приложение клиента или список выбора банка

qrUrl
string

URL с изображением зарегистрированного QR-кода в СБП

subscriptionId
string

Идентификатор подписки

Request samples

Content type
application/json
Example
{
  • "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

Content type
application/json
Example

Отмена QR

Метод позволяет отменить ранее созданный QR. QRDynamic можно отменить только до момента его оплаты. Для QRVariable отменяет последний активный заказ, до момента его оплаты.

path Parameters
qrId
required
string

Уникальный идентификатор QR

header Parameters
Authorization
required

Responses

Request samples

curl --location --request DELETE 'https://pay-test.raif.ru/api/sbp/v2/qrs/ADAC306DDBF443CA94EBE3FA85CA4872' \
--header 'Authorization: Bearer eyJ0eXA***'

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

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

path Parameters
qrId
required
string

Уникальный идентификатор QR

header Parameters
Authorization
required

Responses

Response Schema: application/json
qrId
string

Идентификатор зарегистрированного QR в СБП

qrStatus
string
Enum: "NEW" "IN_PROGRESS" "CANCELLED" "EXPIRED" "PAID"

Код состояния QR-кода

qrExpirationDate
string

Опциональный параметр для указания срока действия QR-кода. При заполнении не может быть меньше текущей даты и времени. После истечения срока действия QR-кода оплату по нему провести нельзя. Если Тип QR = QRDynamic и поле не заполнено, срок действия будет 3 суток. ISO 8601

payload
string

Данные для самостоятельной генерации изображения зарегистрированного QR-кода в СБП. При открытии с мобильного устройства, запускает банковское приложение клиента или список выбора банка

qrUrl
string

URL с изображением зарегистрированного QR-кода в СБП

subscriptionId
string

Идентификатор подписки

Request samples

curl --location --request GET 'https://pay-test.raif.ru/api/sbp/v2/qrs/ADAC306DDBF443CA94EBE3FA85CA4872' \
--header 'Authorization: Bearer eyJ0eXA***'

Response samples

Content type
application/json
{}

Получение списка банков

Получение списка банков, принимающих возвраты по СБП.

header Parameters
Authorization
required

Responses

Response Schema: application/json
Array
alias
string

Алиас Банка

name
string

Наименование Банка

Response samples