Raiff logo
Documentation Powered by ReDoc

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 банка.

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

Схема работы с формой

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

Схема работы по прямому протоколу СБП

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

На рисунке изображена схема информационного обмена c партнёром при реализации платежа по QR-коду.

Схема работы с подписками

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

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

Схема работа по подпискам с оплатой

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

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

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

Схема работы c Кассовой ссылкой СБП

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

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

Мобильная версия и приложение

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

У клиента откроется мобильное приложение банка или список для выбора банка.

Тестирование

Для полного цикла тестирования оплаты Райффайзенбанк предоставляет возможность использования демо-приложения для сканирования QR-кода от имени покупателя по адресу: https://pay.raif.ru/pay/rfuture/

Указанный адрес можно открыть в браузере любого устройства, где есть камера. Никакого дополнительного софта/плагинов устанавливать не нужно. Далее нажать на значок СБП (при необходимости разрешить браузеру доступ к камере) и поднести к ней изображение QR-кода. Если камера не открылась, проверьте, что в адресе указан протокол HTTPS.

Работа с QR-кодом

Для реализации взаимодействия с партнёром Райффайзенбанк предоставляет API из следующих запросов:

  • регистрация QR-кода,
  • отмена QR-кода,
  • получение данных по зарегистрированному ранее QR-коду,
  • получение данных по платежу,
  • возврат денежных средств - может быть выполнен в любое время после проведения оплаты на полную сумму платежа или частичную. Однако сумма частичных запросов на возврат не должна превышать общую сумму заказа.
  • получение информации по возврату.

Схема взаимодействия.

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

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

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

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

header Parameters
Content-Type
required
string

application/json

Request Body schema: application/json
qrType
required
string

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

QRStatic
QRStatic
QRDynamic
QRVariable
account
number <= 20

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

additionalInfo
string <= 140 characters

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

amount
number

Сумма в рублях

currency
string 3 characters
Value: "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>

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

sbpMerchantId
required
string <= 12 characters

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

Responses

Request samples

Content type
application/json
Example
QRVariable
QRVariable
QRDynamic
QRDynamic (2)
QRDynamic subscription
QRStatic
{
  • "account": 40700000000000000000,
  • "qrType": "QRVariable",
  • "sbpMerchantId": "MA0000000552"
}

Response samples

Content type
application/json
Example
QRDynamic subscription
QRDynamic subscription
QRDynamic/QRStatic
QRVariable
{}

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

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

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

header Parameters
Content-Type
required
string

application/json

Request Body schema: application/json
qrType
required
string

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

QRStatic
QRStatic
QRDynamic
account
number <= 20

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

additionalInfo
string <= 140 characters

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

amount
number

Сумма в рублях

currency
string 3 characters
Value: "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>

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

sbpMerchantId
required
string <= 12 characters

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

Responses

Request samples

Content type
application/json
Example
QRDynamic
QRDynamic
QRDynamic (2)
QRDynamic subscription
QRStatic
{
  • "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
QRDynamic subscription
QRDynamic subscription
QRDynamic/QRStatic
{}

Отмена QR-кода

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

path Parameters
qrId
required
string

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

header Parameters
Authorization
required

Responses

Request samples 

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

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

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

path Parameters
qrId
required
string

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

header Parameters
Authorization
required

Responses

Request samples 

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

Response samples

Content type
application/json
{}

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

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

path Parameters
qrId
required
string

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

header Parameters
Authorization
required

Responses

Request samples 

curl --location --request GET 'https://test.ecom.raiffeisen.ru/api/sbp/v1/qr/AS6E5A7F9E3A4E648C536EC930AECDF6/info' \
--header 'Authorization: Bearer eyJ0eXA***'

Response samples

Content type
application/json
{}

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

Метод позволяет получить данные по платежу по QR

path Parameters
qrId
required
string

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

header Parameters
Authorization
required

Responses

Request samples 

curl --location --request GET 'https://test.ecom.raiffeisen.ru/api/sbp/v1/qr/AS6E5A7F9E3A4E648C536EC930AECDF6/payment-info' \
--header 'Authorization: Bearer eyJ0eXA***'

Response samples

Content type
application/json
{
  • "additionalInfo": "Доп. информация",
  • "paymentPurpose": "Назначение платежа",
  • "amount": 1110.11,
  • "code": "SUCCESS",
  • "createDate": "2020-01-31T09:14:38.107227+03:00",
  • "currency": "RUB",
  • "merchantId": 123,
  • "order": "282a60f8-dd75-4286-bde0-af321dd081b3",
  • "paymentStatus": "SUCCESS",
  • "qrId": "AD100051KNSNR64I98CRUJUASC9M72QT",
  • "sbpMerchantId": "MA0000000552",
  • "transactionDate": "2019-07-11T17:45:13.109227+03:00",
  • "transactionId": 23,
  • "qrExpirationDate": "2020-01-15T13:00:40+03:00"
}

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

Метод позволяет осуществлять полный и частичный возврат по QR

header Parameters
Content-Type
required
string

application/json

Authorization
required
Request Body schema: application/json
amount
required
number

Сумма возврата в рублях

order
required
string <= 40 characters

Уникальный идентификатор заказа в системе партнёра

paymentDetails
string <= 140 characters

Назначение платежа

refundId
required
string <= 40 characters

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

transactionId
number

Идентификатор операции платежа в Райффайзенбанке, обязателен только для QRStatic

Responses

Request samples

Content type
application/json
Example
QRDynamic
QRDynamic
QRStatic
{
  • "amount": 150,
  • "order": "test_order_007",
  • "paymentDetails": "Test",
  • "refundId": "test_refundId_007"
}

Response samples

Content type
application/json
{
  • "code": "SUCCESS",
  • "amount": 150,
  • "refundStatus": "IN_PROGRESS"
}

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

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

path Parameters
refundId
required
string

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

header Parameters
Authorization
required

Responses

Request samples 

curl --location --request GET 'https://test.ecom.raiffeisen.ru/api/sbp/v1/refund/111112222200046' \
--header 'Authorization: Bearer eyJ0eXA***'

Response samples

Content type
application/json
{
  • "code": "SUCCESS",
  • "amount": 150,
  • "refundStatus": "COMPLETED"
}

Кассовая ссылка СБП

Для реализации взаимодействия с QRVariable (Кассовой ссылкой) Райффайзенбанк предоставляет API из следующих запросов:

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

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

Схема взаимодействия приведена выше.

Создание заказа

Метод позволяет создать новый заказ без возможности его редактирования. Для связки заказа с QR-кодом (с типом QRVariable) необходимо также передать блок с данными о QR в теле запроса. Необходимо передать тот идентификатор QR-кода, который был получен в ответе на запрос регистрации QR-кода.

header Parameters
Authorization
required
Content-Type
required
string

application/json

Request Body schema: application/json
id
string [ 1 .. 40 ] characters ^[A-z0-9-_.]

Уникальный идентификатор заказа. Рекомендуется использовать формат, не допускающий возможность перебора, например, UUID v4
Если параметр не передан, то идентификатор присвоится заказу автоматически

amount
required
number <float>

Сумма заказа

comment
string

Комментарий к заказу

extra
object

Дополнительные поля