Raiff logo
API docs by Redocly

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

Download OpenAPI specification:Download

Support e-mail: ecom@raiffeisen.ru

Тестирование СБП

Для получения тестовых данных для интеграции напишите на ecom@raiffeisen.ru. В ответном письме мы отправим вам токен для авторизации в тестовой среде и два счёта для тестирования сервиса.

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

Для приёма и / или отправки СБП-платежей оставьте заявку в РБО → Продукты → В2В-платежи по СБП.

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

Схема работы

На схеме ниже представлен сценарий работы с заказом со стороны Получателя.

Авторизация

Для авторизация запросов необходимы:

  • secretKey - секретный ключ, который используется для межсервисного взаимодействия.

Тестовый хост: https://pay-test.raif.ru

Продуктовый хост: https://pay.raif.ru

BАЖНО: Секретный ключ необходимо хранить в защищённом месте, нельзя публиковать на сторонних ресурсах или передавать третьим лицам.

Межсервисные запросы авторизуются посредством секретного ключа API (SECRET_KEY). Параметр авторизации указывается в заголовке Authorization, значение которого формируется как "Bearer SECRET_KEY".

Посмотреть боевой publicId и сгенерировать ключи можно в РБО → Прием платежей → Настройки.

Для генерации тестового секретного ключа необходимо обратиться по адресу: ecom@raiffeisen.ru

Наложение подписи на запрос создания одиночного платежа B2B

Такой запрос требует наличия подписи, выполненной с помощью приватного ключа, выданного банком в личном кабинете РБО.

Post-запрос должен содержать три http-заголовка: Content-Digest, Signature а также Authorization.

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

Пример:

"{\"account\":\"1234567890\",\"amount\":10.0,\"totalTaxAmount\":0.0,\"paymentPurpose\":\"test\",\"extra\":null}"

Если поле имеет числовой тип, то в json это должно быть именно число, если поле null, то оно также должно присутствовать (пример extra).

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

Получатель

Получение данных заказа

path Parameters
id
required
string

Уникальный идентификатор заказа (поле id из ответа на запрос создания заказа)

header Parameters
Authorization
required
string
Example: eyJ0eXA***

Responses

Response samples

Content type
application/json
Example

Ответ на создание заказа без указаниям ограничений Отсутствует блок restrictions

{}

Генерация изображения платёжной ссылки

path Parameters
qrId
required
string

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

query Parameters
format
string
Default: "SVG"

Формат изображения

withLogo
boolean
Default: true

Отображение логотипа СБП в QR-коде

Responses

Регистрация платёжной ссылки Deprecated

header Parameters
Authorization
required
string
Example: eyJ0eXA***
Request Body schema: application/json
required
qrType
required
string
Enum: "DYNAMIC" "STATIC"

Тип платёжной ссылки. Возможные значения:
• DYNAMIC – для динамической (разовой) платёжной ссылки
• STATIC – для статической (многоразовой) платёжной ссылки

qrName
string <= 255 characters

Наименование платёжной ссылки

account
required
string = 20 characters

Банковский счёт ЮЛ или ИП для зачисления средств

takeTax
required
boolean

Информация о взимании НДС. Допустимые значения:
• true – облагается НДС
• false – не облагается НДС
Если платеж облагается НДС (takeTax = "true") обязательно должна быть заполнена сумма НДС в поле totalTaxAmount

totalTaxAmount
number <float> <= 1000000

Сумма НДС в рублях. Поле не заполняется при takeTax = "false". Поле обязательное при qrType = "DYNAMIC" И takeTax = "true". Не должна превышать значение суммы операции (amount)

amount
number <float> <= 1000000

Сумма операции в рублях. Поле обязательное при qrType = "DYNAMIC" ИЛИ qrType = "STATIC" И takeTax = "true" И totalTaxAmount не пустое значение. Максимальное значение - 1000000 рублей

paymentPurpose
string <= 210 characters

Назначение платежа. Поле обязательное при qrType = "DYNAMIC".
Может содержать:
• Символы латинского алфавита (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

expirationDate
string <date-time>

Срок жизни платёжной ссылки. Поле не заполняется при qrType = "STATIC". Если указывается в минутах, то не может быть меньше 1 минуты. Максимальное значение - 90 суток. Если параметр не передан, то по умолчанию QR будет действителен 3 суток. После истечения срока действия QR-кода оплату по нему провести нельзя.

redirectUrl
string <= 1024 characters

Cсылка для автоматического возврата плательщика из приложения банка в приложение или на сайт ТСП. Допускаются только символы в кодировке ASCII. Формат должен соответствовать спецификации RFC-3986

orderId
string <= 35 characters ^[A-z0-9-_.]+$

УИП (уникальный идентификатор платежа). Поле не заполняется при qrType = "STATIC"

extra
object

Дополнительные поля. Словарь с ключами и значениями типа String

Responses

Request samples

Content type
application/json
{
  • "qrType": "DYNAMIC",
  • "qrName": "Оплата услуги",
  • "account": "40817810601002630020",
  • "takeTax": true,
  • "totalTaxAmount": 2.41,
  • "amount": 8573.79,
  • "paymentPurpose": "Какое-то назначение платежа",
  • "expirationDate": "2019-08-24T14:15:22Z",
  • "redirectUrl": "https://exampletsp.io/qwertyui",
  • "orderId": "281000670LSS7DN18SJQDNP4B05KLJL2",
  • "extra": {
    }
}

Response samples

Content type
application/json
{}

Получение списка зарегистрированных платёжных ссылок Deprecated

query Parameters
page
integer <int32>
Default: 1

Номер страницы

size
integer <int32>
Default: 20

Количество отображаемых платёжных ссылок

fromDate
string <date>

Дата начала периода фильтрации по дате создания платёжной ссылки

toDate
string <date>

Дата окончания периода фильтрации по дате создания платёжной ссылки

qrStatus
string
Enum: "CREATED" "EXPIRED" "PAID"

Статус платёжной ссылки

qrType
string
Enum: "DYNAMIC" "STATIC"

Тип платёжной ссылки

search
string

Поле для поиска по наименованию платёжной ссылке или по сумме операции

header Parameters
Authorization
required
string
Example: eyJ0eXA***

Responses

Response samples

Content type
application/json
{}

Получение данных по зарегистрированной платёжной ссылке Deprecated

path Parameters
qrId
required
string

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

header Parameters
Authorization
required
string
Example: eyJ0eXA***

Responses

Response samples

Content type
application/json
{}

Уведомления об операциях

Для информирования клиента о проведённых платежах могут использоваться 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

Content type
application/json
{
  • "event": "B2B_PAYMENT",
  • "data": {
    }
}

Настройка url для callback

Для подписи уведомлений будет использоваться ключ из заголовка авторизации.

header Parameters
Authorization
required
string
Example: eyJ0eXA***
Request Body schema: application/json
callbackUrl
required
string

URL для приёма уведомлений

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

Реестр

Реестры по платежам отправляются на ежедневной, еженедельной, ежемесячной основе, в зависимости от выставленной настройки. В РБО -> Прием платежей -> Реестры

Инструкция по настройке реестров

В случае отсутствия операций за день, реестр на следующий день не отправляется.

Формат реестра:

Наименование колонки Значение
Мерчант Идентификатор в системе СБП
Дата операции МСК Дата и время проведения операции (МСК)
ID платежной ссылки Уникальный идентификатор платежной ссылки (qrId)
ID операции Внутренний идентификатор платежа
ID операции НСПК Идентификатор операции в системе НСПК
ID заказа Уникальный идентификатор заказа в системе партнёра
Основание операции в выписке Назначение платежа в выписке получателя
Назначение платежа Расширенное Назначение Платежа
Сумма Сумма Операции
НДС Сумма НДС
Дополнительные поля Дополнительные поля, указанные получателем (extra)
Комиссия Комиссия за транзакцию
Наименования плательщика Наименование Юридического Лица Плательщика
Банковский счёт плательщика Номер банковского счета Плательщика
ИНН плательщика Идентификационный номер налогоплательщика Плательщика
ID банка плательщика Идентификатор Банка Плательщика
Наименование банка плательщика Наименование Банка Плательщика
Бик банка плательщика Банковский Идентификационный Код Банка Плательщика

Пример реестра в кодировке WIN-1251

Пример реестра в кодировке UTF-8