API интеграции Системы быстрых платежей (СБП) для B2B
Download OpenAPI specification:Download
Для приёма и / или отправки СБП-платежей оставьте заявку в РБО → Продукты → В2В-платежи по СБП.
Райффайзенбанк выполнит регистрацию. После завершения процесса вы будете оповещены по электронной почте.
Для авторизация запросов необходимы:
- secretKey - секретный ключ, который используется для межсервисного взаимодействия.
Тестовый хост: https://pay-test.raif.ru
Продуктовый хост: https://pay.raif.ru
BАЖНО: Секретный ключ необходимо хранить в защищённом месте, нельзя публиковать на сторонних ресурсах или передавать третьим лицам.
Межсервисные запросы авторизуются посредством секретного ключа API (SECRET_KEY). Параметр авторизации указывается в заголовке Authorization, значение которого формируется как "Bearer SECRET_KEY".
Посмотреть боевой publicId и сгенерировать ключи можно в РБО → Прием платежей → Настройки.
Для генерации тестового секретного ключа необходимо обратиться по адресу: ecom@raiffeisen.ru
Создание заказа
Создается только динамическая платёжная ссылка
header Parameters
| Authorization required |
Request Body schema: application/jsonrequired
| id | string Идентификатор заказа, переданный клиентом или сгенерированный банком |
| name | string Наименование платёжной ссылки |
| account required | string = 20 characters Банковский счёт ЮЛ или ИП для зачисления средств |
| amount required | number <float> <= 1000000 Сумма операции в рублях |
| totalTaxAmount | number or null <float> <= 1000000 Сумма НДС в рублях |
| expirationDate | string <yyyy-MM-ddTHH:mm:ss±HH:mm / +nM / +nm> Срок жизни заказа
|
| receiverPaymentPurpose | string <= 100 characters Назначение платежа, которое увидит получатель в выписке в поле «Основание операции» вместе с инн плательщика.
|
| senderPaymentPurpose required | string <= 210 characters Назначение платежа, которое увидит плательщик при оплате. Поле обязательное.
|
| redirectUrl | string <= 1024 characters Ссылка для автоматического возврата плательщика из приложения банка в приложение или на сайт ТСП |
| extra | object Дополнительные поля |
object or null Ограничения к заказу |
Responses
Request samples
- Payload
Запрос на создание заказа c указанием количества минут жизни
{- "id": "281000670LSS7DN18SJQDNP4B05KLJL2",
- "name": "QR на оплату 25.09.2024 в 15:12",
- "account": "40817810601002630000",
- "amount": 7.45,
- "totalTaxAmount": 1.25,
- "expirationDate": "+60m",
- "receiverPaymentPurpose": "Какое-то назначение платежа",
- "senderPaymentPurpose": "Какое-то назначение платежа",
- "extra": {
- "additionalInfo": "testing operation"
}
}Response samples
- 200
- 400
- 403
- 500
Ответ на создание заказа без указания ограничений Отсутствует блок restrictions
{- "id": "281000670LSS7DN18SJQDNP4B05KLJL2",
- "account": "40817810601002630000",
- "amount": 8573.79,
- "totalTaxAmount": 2.41,
- "creationDate": "2024-06-12T19:35:55+03:00",
- "expirationDate": "2024-08-12T20:35:55+03:00",
- "status": "ACTIVE",
- "receiverPaymentPurpose": "Какое-то назначение платежа",
- "senderPaymentPurpose": "Какое-то назначение платежа",
- "extra": {
- "additionalInfo": "testing operation"
}, - "qr": {
- "id": "AS1B001K33DNHAKV2KNBJRQK6KHNQKJ5",
- "name": "QR на оплату 25.09.2024 в 15:12",
- "type": "DYNAMIC",
}
}Отмена заказа
Метод позволяет отменить неоплаченный заказ. После отмены оплата заказа с текущим id будет недоступна. Но вы можете переиспользовать этот id для создания нового заказа
path Parameters
| id required | string Идентификатор заказа |
header Parameters
| Authorization required |
Responses
Response samples
- 403
- 404
- 500
{- "code": "FORBIDDEN",
- "message": "Доступ запрещен"
}Получение данных заказа
path Parameters
| id required | string Идентификатор заказа |
header Parameters
| Authorization required |
Responses
Response samples
- 200
- 403
- 404
- 500
Ответ на создание заказа без указаниям ограничений Отсутствует блок restrictions
{- "id": "281000670LSS7DN18SJQDNP4B05KLJL2",
- "account": "40817810601002630000",
- "amount": 8573.79,
- "totalTaxAmount": 2.41,
- "creationDate": "2024-06-12T19:35:55+03:00",
- "expirationDate": "2024-08-12T20:35:55+03:00",
- "status": "ACTIVE",
- "receiverPaymentPurpose": "Какое-то назначение платежа",
- "senderPaymentPurpose": "Какое-то назначение платежа",
- "extra": {
- "additionalInfo": "testing operation"
}, - "qr": {
- "id": "AS1B001K33DNHAKV2KNBJRQK6KHNQKJ5",
- "name": "QR на оплату 25.09.2024 в 15:12",
- "type": "DYNAMIC",
}
}Для информирования клиента о проведённых платежах могут использоваться HTTP-уведомления на адрес, указанный в его настройках.
Боевой адрес можно указать в личном кабинете во вкладке "Прием платежей"
Также адрес для тестовой и боевой среды можно указать с помощью метода в API.
Для партнёра уведомление представляет собой входящий POST-запрос, который использует JSON-структуру.
Уведомление считается принятым, если получатель ответил на запрос кодом HTTP 200.
Ответы с любыми другими HTTP-кодами будут считаться невалидными. Повторные попытки отправки будут проводиться в течение суток с нарастающим интервалом.
Для проверки подлинности уведомления по QRStatic и QRDynamic к данным добавляется подпись в заголовке X-Api-Signature-SHA256
, полученная на основе общего секретного ключа и контрольной строки id|qr.id|payment.id|payment.status.value|payment.amount|payment.status.date
с помощью HMAC-SHA-256.
Необходимо проверять сумму для проверки корректности уведомления.
Уведомления отправляются с IP 193.28.44.23
Уведомление о входящем платеже Webhook
Request Body schema: application/json
| event | string Value: "B2B_PAYMENT" Тип операции |
object |
Responses
Request samples
- Payload
{- "event": "B2B_PAYMENT",
- "data": {
- "id": "string",
- "account": "40817810601002630020",
- "amount": 8573.79,
- "totalTaxAmount": 2.41,
- "createdDate": "2024-06-12T19:35:55+03:00",
- "expirationDate": "2024-08-12T20:35:55+03:00",
- "status": "ACTIVE",
- "receiverPaymentPurpose": "Какое-то назначение платежа",
- "senderPaymentPurpose": "Какое-то назначение платежа",
- "extra": {
- "additionalInfo": "testing operation"
}, - "qr": {
- "id": "AS1B001K33DNHAKV2KNBJRQK6KHNQKJ5",
- "name": "QR на оплату 14.10.2024 в 15:12",
- "type": "DYNAMIC",
}, - "payment": {
- "id": 123456789012345680,
- "sbpTransactionId": "PMSHT0BYVSYE7LDXMCXJSGIUHJLQWZXY",
- "status": {
- "value": "SUCCESS",
- "date": "2024-06-12T19:36:55+03:00"
}, - "amount": 8573.79,
- "totalTaxAmount": 2.41,
- "sender": {
- "legalName": "ООО Ромашка",
- "inn": "123456789012",
- "account": "40817810601002630020",
- "bank": {
- "id": 100000000007,
- "name": "Райффайзенбанк",
- "bic": "044525700"
}
}
}
}
}Настройка url для callback
Для подписи уведомлений будет использоваться ключ из заголовка авторизации.
header Parameters
| Authorization required |
Request Body schema: application/json
| callbackUrl required | string URL для приёма уведомлений |
Responses
Request samples
- Payload
{
}Response samples
- 200
{
}Реестры по платежам отправляются на ежедневной, еженедельной, ежемесячной основе, в зависимости от выставленной настройки. В РБО -> Прием платежей -> Реестры
Инструкция по настройке реестров
В случае отсутствия операций за день, реестр на следующий день не отправляется.
Формат реестра:
| Наименование колонки | Значение |
|---|---|
| Мерчант | Идентификатор в системе СБП |
| Дата операции МСК | Дата и время проведения операции (МСК) |
| ID платежной ссылки | Уникальный идентификатор платежной ссылки (qrId) |
| ID операции | Внутренний идентификатор платежа |
| ID операции НСПК | Идентификатор операции в системе НСПК |
| ID заказа | Уникальный идентификатор заказа в системе партнёра |
| Основание операции в выписке | Назначение платежа в выписке получателя |
| Назначение платежа | Расширенное Назначение Платежа |
| Сумма | Сумма Операции |
| НДС | Сумма НДС |
| Дополнительные поля | Дополнительные поля, указанные получателем (extra) |
| Комиссия | Комиссия за транзакцию |
| Наименования плательщика | Наименование Юридического Лица Плательщика |
| Банковский счёт плательщика | Номер банковского счета Плательщика |
| ИНН плательщика | Идентификационный номер налогоплательщика Плательщика |
| ID банка плательщика | Идентификатор Банка Плательщика |
| Наименование банка плательщика | Наименование Банка Плательщика |
| Бик банка плательщика | Банковский Идентификационный Код Банка Плательщика |
Для получения тестовых данных для интеграции напишите на ecom@raiffeisen.ru. В ответном письме мы отправим вам токен для авторизации в тестовой среде и два счёта для тестирования сервиса.
Ниже представлены запросы ТОЛЬКО для тестового окружения, запросы для продуктового окружения описаны тут
Также для тестовой платы можно использовать R-Future со сканированием qr. Для оплаты методом сканирования нужно открыть ссылку imageUrl(в ответе на создание qr) или перейти по адресу https://pay-test.raif.ru/api/b2b/sbp/v1/qrs/{qrId}/image - появится изображение QR Далее открыть https://pay-test.raif.ru/pay/rfuture/# нажать кнопку "Сканировать QR", навести камеру и появится форма оплаты, по которой можно произвести платеж.
Создание тестовой оплаты
!! Данные endpoint можно использовать только в ТЕСТОВОМ окружении !!
path Parameters
| qrId required | string Уникальный идентификатор платёжной ссылки |
Request Body schema: application/jsonrequired
| amount required | number <float> (Amount) <= 1000000 Сумма операции в рублях |
Responses
Request samples
- Payload
{- "amount": 8573.79
}Response samples
- 400
{- "code": "INVALID_DATA",
- "message": "Некорректные данные"
}