Download OpenAPI specification:Download
Свои предложения и идеи о документации можно оставить в репозитории по адресу: https://github.com/Raiffeisen-DGTL/ecom-API/blob/master/sbp.yaml
Для приема СБП-платежей оставьте заявку на сайте.
Райффайзенбанк выполнит регистрацию. После завершения процесса вы будете оповещены по электронной почте.
По закону от 22.05.2003 № 54–ФЗ "О применении контрольно-кассовой техники при осуществлении расчетов в Российской Федерации" при оплате товаров, работ или услуг необходимо формировать фискальный чек и отправлять его в налоговую с помощью кассы.
Райффайзенбанк предоставляет возможность фискализировать чеки через API банка.
B случае если прием платежей планируется на сайте или в мобильном приложении, рекомендуем использовать протокол с отображением QR-кода на нашей форме.
Вы можете предложить клиенту привязать оплату по СБП к программе лояльности или к аккаунту в вашем сервисе. Для этого вы можете сгенерировать QR-код и отобразить его клиенту либо перенаправить его на специальную ссылку, которая есть в ответе на запрос генерации QR-кода на подписку.
После по уникальному идентификатору подписки вы можете обращаться за безакцептным списанием средств с клиента за ваши товары и услуги.
Также есть схема, когда одним запросом создается QR-код на получение оплаты и заведение подписки.
В данном случае клиент проводит оплату, после чего ему отображается окно с предложением подключения подписки.
Клиент может провести оплату, но отказаться от подписки. Также клиент может провести оплату из приложения банка, который не подключен к сервису подписок.
Механизм подписок также поддерживает регулярные автоматические списания, которые банк проводит в указанную дату в 10:00 или 13:00 по московскому времени. На данный момент поддерживаются только ежемесячные списания. При неуспешной оплате в 10:00 производится еще одна попытка в 13:00 того же дня, при повторной ошибке будет еще по две попытки в последующие дни в то же время. Неуспешность платежа не ведет к отмене подписки.
Автоматические списания возможны как для оплаты с последующей подпиской, так и для подписки без оплаты в этот момент. Для автоматических платежей необходимо передать дополнительные параметры списания в методе создания QR или методе создания подписки.
Сообщения о платежах можно получать в виде callback-уведомлений. В теле сообщения в объекте extra будет приходить ключ, переданный ранее при создании подписки или QR. Деактивировать подписку можно методом отмены подписки.
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 взамен 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-коды и кассовую ссылку СБП (QRVariable) для каждой кассы. Также с помощью данного метода вы можете сгенерировать QR-код для оплаты с подпиской.
При каждом новом запросе будет возвращаться новый QR.
Тестовые QR можно оплатить только с помощью тестового приложения.
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 Идентификатор зарегистрированного партнёра в СБП |
redirectUrl | string <uri> Ссылка для автоматического возврата плательщика из приложения банка в приложение или на сайт магазина. Ссылка должна содержать https:// для web страниц или уникальную схему для мобильного приложения |
qrDescription | string <= 32 characters Описание QR-кода |
object Используется для оплаты с последующей подпиской | |
object Дополнительные поля для свободного заполнения по принципу key-value |
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 Идентификатор подписки |
{- "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",
- "qrDescription": "QR для оплаты заказа"
}
{- "qrId": "AD1F2CD7212E48FA919AB52EF0AEFB33",
- "qrStatus": "NEW",
- "subscriptionId": "120059"
}
Метод позволяет генерировать как статические QR-коды, так и динамические QR-коды. Также с помощью данного метода вы можете сгенерировать QR-код для оплаты с подпиской.
Тестовые QR можно оплатить только нашим тестовым приложением.
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 Идентификатор зарегистрированного партнёра в СБП |
redirectUrl | string <uri> Ссылка для автоматического возврата плательщика из приложения банка в приложение или на сайт магазина. Ссылка должна содержать https:// для web страниц или уникальную схему для мобильного приложения |
qrDescription | string <= 32 characters Описание QR-кода |
object Используется для оплаты с последующей подпиской | |
object Дополнительные поля для свободного заполнения по принципу key-value |
code | string <= 140 characters Код сообщения |
qrId | string <= 32 characters Идентификатор зарегистрированного QRС в СБП |
payload | string Данные для самостоятельной генерации изображения зарегистрированного QR-кода в СБП. При открытии с мобильного устройства запускает банковское приложение клиента или список выбора банка |
qrUrl | string URL с изображением зарегистрированного QR-кода в СБП |
subscriptionId | string Идентификатор подписки |
{- "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"
}
{- "code": "SUCCESS",
- "qrId": "AD1F2CD7212E48FA919AB52EF0AEFB33",
- "subscriptionId": "120059"
}
Метод позволяет отменить ранее созданный QR. QRDynamic можно отменить только до момента его оплаты. Для QRVariable отменяет последний активный заказ, до момента его оплаты.
qrId required | string Уникальный идентификатор QR |
Authorization required | string |
curl --location --request DELETE 'https://pay-test.raif.ru/api/sbp/v2/qrs/ADAC306DDBF443CA94EBE3FA85CA4872' \ --header 'Authorization: Bearer eyJ0eXA***'
Метод позволяет получить данные по зарегистрированному ранее QR-коду
qrId required | string Уникальный идентификатор QR |
Authorization required | string |
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 Идентификатор подписки |
curl --location --request GET 'https://pay-test.raif.ru/api/sbp/v2/qrs/ADAC306DDBF443CA94EBE3FA85CA4872' \ --header 'Authorization: Bearer eyJ0eXA***'
{- "qrId": "AD100004BAL7227F9BNP6KNE007J9B3K",
- "qrStatus": "NEW",
- "qrExpirationDate": "2023-07-22T09:14:38+03:00",
}