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

Получатель

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

path Parameters
id
required
string

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

header Parameters
Authorization
required
string
Example: eyJ0eXA***

Responses

Response Schema: application/json
id
required
string <= 35 characters ^[A-z0-9-_.]+$

Идентификатор заказа. Если не был передан в запросе на создание, то генерируется банком самостоятельно

account
required
string 20 characters

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

amount
required
number <float> <= 1000000

Сумма операции в рублях

totalTaxAmount
number or null <float> <= 1000000

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

createdDate
required
string <date-time>

Дата создания платёжной ссылки

expirationDate
required
string <date-time>

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

status
required
string
Enum: "ACTIVE" "EXPIRED" "PAID"

Статус заказа:
• ACTIVE – активен
• EXPIRED - срок действия истёк
• PAID - оплачен

senderPaymentPurpose
required
string <= 210 characters

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

redirectUrl
string <= 1024 characters

Ссылка для автоматического возврата плательщика из приложения банка в приложение или на сайт ТСП

extra
object

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

object or null

Ограничение к заказу

required
object

Информация о платёжной ссылке по заказу

object or null

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

Response samples

Content type
application/json
Example

Ответ на запрос статуса, когда заказ был оплачен — status = PAID

{
  • "id": "281000670LSS7DN18SJQDNP4B05KLJL2",
  • "account": 40817810601002630000,
  • "amount": 8573.79,
  • "totalTaxAmount": 2.41,
  • "createdDate": "2024-06-12Т19:35:55+03:00",
  • "expirationDate": "2024-08-12Т20:35:55+03:00",
  • "status": "PAID",
  • "senderPaymentPurpose": "Какое-то назначение платежа",
  • "extra": {
    • "additionalInfo": "testing operation"
    },
  • "restrictions": {
    • "senderInn": "123456789012"
    },
  • "qr": {},
  • "payment": {
    • "id": 123456789012345680,
    • "sbpTransactionId": "PMSHT0BYVSYE7LDXMCXJSGIUHJLQWZXY",
    • "status": {
      • "value": "SUCCESS",
      • "date": "2024-06-12Т19:36:55+03:00"
      },
    • "amount": 8573.79,
    • "totalTaxAmount": 2.41,
    • "sender": {
      • "legalName": "ООО Ромашка",
      • "inn": 123456789012,
      • "bank": {
        • "id": 100000000007,
        • "name": "Райффайзенбанк",
        • "bic": 44525700
        }
      }
    }
}

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

path Parameters
qrId
required
string

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

query Parameters
format
string
Default: "SVG"

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

withLogo
boolean
Default: true

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

Responses

Response Schema: application/xml
string <byte>

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

header Parameters
Authorization
required
string
Example: eyJ0eXA***
Request Body schema: application/json
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

Дополнительные поля. Строка в формате json

Responses

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

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

qrType
required
string
Enum: "DYNAMIC" "STATIC"

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

qrName
string <= 255 characters

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

account
required
string 20 characters

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

takeTax
required
boolean

Информация о взимании НДС

totalTaxAmount
number <float> <= 1000000

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

amount
number <float> <= 1000000

Сумма операции в рублях

paymentPurpose
string <= 210 characters

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

creationDate
required
string <date-time>

Дата создания платёжной ссылки

expirationDate
string <date-time>

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

redirectUrl
string <= 1024 characters

Cсылка для автоматического возврата плательщика из приложения банка в приложение или на сайт ТСП

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

УИП (уникальный идентификатор платежа)

payload
required
string <= 999 characters

Функциональная ссылка

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

Статус платёжной ссылки:
• CREATED – создана
• EXPIRED - срок действия истёк
• PAID - оплачен

qrUrl
string

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

extra
object

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

Request samples

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

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 Schema: application/json
Array of objects (QrResponseDto) [ items ]
object (Meta)

Response samples

Content type
application/json
{}

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

path Parameters
qrId
required
string

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

header Parameters
Authorization
required
string
Example: eyJ0eXA***

Responses

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

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

qrType
required
string
Enum: "DYNAMIC" "STATIC"

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

qrName
string <= 255 characters

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

account
required
string 20 characters

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

takeTax
required
boolean

Информация о взимании НДС

totalTaxAmount
number <float> <= 1000000

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

amount
number <float> <= 1000000

Сумма операции в рублях

paymentPurpose
string <= 210 characters

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

creationDate
required
string <date-time>

Дата создания платёжной ссылки

expirationDate
string <date-time>

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

redirectUrl
string <= 1024 characters

Cсылка для автоматического возврата плательщика из приложения банка в приложение или на сайт ТСП

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

УИП (уникальный идентификатор платежа)

payload
required
string <= 999 characters

Функциональная ссылка

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

Статус платёжной ссылки:
• CREATED – создана
• EXPIRED - срок действия истёк
• PAID - оплачен

qrUrl
string

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

extra
object

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

Response samples

Content type
application/json
{}

Плательщик

Получение данных платёжной ссылки

path Parameters
qrId
required
string <= 32 characters

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

header Parameters
Authorization
required
string
Example: eyJ0eXA***

Responses

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

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

qrType
required
string
Enum: "DYNAMIC" "STATIC"

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

takeTax
required
boolean

Информация о взимании НДС

totalTaxAmount
number <float> <= 1000000

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

amount
number <float> <= 1000000

Сумма операции в рублях

paymentPurpose
string <= 210 characters

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

legalName
required
string <= 512 characters

Сокращённое наименование ЮЛ или ИП получателя

inn
required
string [ 10 .. 12 ] characters

ИНН ЮЛ или ИП получателя

brandName
required
string <= 35 characters

Торговое наименование ТСП получателя

address
required
string <= 140 characters

Фактический адрес ТСП получателя

required
object

Данные банка получателя

required
object (MccCodeDto)
redirectUrl
string <= 1024 characters

Содержит ссылку для автоматического возврата Плательщика из приложения Банка в приложение или на сайт ТСП

Response samples

Content type
application/json
{
  • "qrId": "AS1B001K33DNHAKV2KNBJRQK6KHNQKJ5",
  • "qrType": "DYNAMIC",
  • "takeTax": true,
  • "totalTaxAmount": 2.41,
  • "amount": 8573.79,
  • "paymentPurpose": "Какое-то назначение платежа",
  • "legalName": "ООО Торг",
  • "inn": 4285733785,
  • "brandName": "ООО Торг на Б.Татарской",
  • "address": "г. Москва, ул. Б.Татарская, д.133, стр.1",
  • "bank": {
    • "id": 100000000007,
    • "name": "Райффайзенбанк",
    • "bic": 44525700
    },
  • "mcc": {
    • "code": 4121,
    • "title": "Лимузины и такси"
    },
}

Создание платежа

path Parameters
qrId
required
string <= 32 characters

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

header Parameters
Authorization
required
string
Example: eyJ0eXA***
Request Body schema: application/json
account
required
string 20 characters

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

takeTax
required
boolean

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

totalTaxAmount
number <float> <= 1000000

Сумма НДС в рублях. Поле не заполняется при takeTax = "false". Если сумма НДС указана в реквизитах платёжной ссылки, то используется значение из этих реквизитов. Иначе, заполняется плательщиком самостоятельно. Сумма НДС не должна превышать сумму операции (amount)

amount
required
number <float> <= 1000000

Сумма операции в рублях. Если сумма операции указана в реквизитах платёжной ссылки, то используется значение из этих реквизитов. Иначе, заполняется плательщиком самостоятельно. Максимальное значение - 1000000 рублей

paymentPurpose
required
string <= 210 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

extra
object

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

Responses

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

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

transactionId
required
string

Идентификатор операции в Райффайзенбанке

createdDate
required
string <date-time>

Дата и время создания платежа

account
required
string 20 characters

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

takeTax
required
boolean

Информация о взимании НДС. Допустимые значения:
• true – облагается НДС
• false – не облагается НДС

totalTaxAmount
number <float> <= 1000000

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

amount
required
number <float> <= 1000000

Сумма операции в рублях

paymentPurpose
required
string <= 210 characters

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

extra
object

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

Request samples

Content type
application/json
{
  • "account": 40817810601002630000,
  • "takeTax": true,
  • "totalTaxAmount": 2.41,
  • "amount": 8573.79,
  • "paymentPurpose": "Какое-то назначение платежа",
  • "extra": {
    • "additionalInfo": "testing operation"
    }
}

Response samples

Content type
application/json
{
  • "qrId": "AS1B001K33DNHAKV2KNBJRQK6KHNQKJ5",
  • "transactionId": 10092,
  • "createdDate": "2019-08-24T14:15:22Z",
  • "account": 40817810601002630000,
  • "takeTax": true,
  • "totalTaxAmount": 2.41,
  • "amount": 8573.79,
  • "paymentPurpose": "string",
  • "extra": {
    • "additionalInfo": "testing operation"
    }
}

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

path Parameters
qrId
required
string <= 32 characters

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

transactionId
required
string

Идентификатор операции в Райффайзенбанке

header Parameters
Authorization
required
string
Example: eyJ0eXA***

Responses

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

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

transactionId
required
string

Идентификатор операции в Райффайзенбанке

sbpTransactionId
string 32 characters

Уникальный идентификатор операции на уровне всей системы СБП

account
required
string 20 characters

Счёт списания

transactionDate
required
string <date-time>

Дата и время проведения платежа

createdDate
required
string <date-time>

Дата и время создания платежа

paymentStatus
required
string
Enum: "SUCCESS" "FAILED" "IN_PROGRESS"

Статус платежа

paymentPurpose
required
string <= 210 characters

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

takeTax
required
boolean

Информация о взимании НДС

totalTaxAmount
number <float> <= 1000000

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

amount
required
number <float> <= 1000000

Сумма операции в рублях

extra
object

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

object (ReceiverDto)

Response samples

Content type
application/json
{
  • "qrId": "AS1B001K33DNHAKV2KNBJRQK6KHNQKJ5",
  • "transactionId": 10092,
  • "sbpTransactionId": "B1A2S3D5F6G7H8J9K0C4S5C6D7V5D1K3",
  • "account": 40817810601002630000,
  • "transactionDate": "2019-08-24T14:15:22Z",
  • "createdDate": "2019-08-24T14:15:22Z",
  • "paymentStatus": "SUCCESS",
  • "paymentPurpose": "Какое-то назначение платежа",
  • "takeTax": true,
  • "totalTaxAmount": 2.41,
  • "amount": 8573.79,
  • "extra": {
    • "additionalInfo": "testing operation"
    },
  • "receiver": {
    • "legalName": "ООО Торг",
    • "inn": 4285733785,
    • "brandName": "ООО Торг на Б.Татарской",
    • "address": "г. Москва, ул. Б.Татарская, д.133, стр.1",
    • "mcc": {
      • "code": 4121,
      • "title": "Лимузины и такси"
      }
    }
}

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

Для информирования клиента о проведенных платежах могут использоваться 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": {
    • "id": "281000670LSS7DN18SJQDNP4B05KLJL2",
    • "account": 40817810601002630000,
    • "amount": 8573.79,
    • "totalTaxAmount": 2.41,
    • "createdDate": "2024-06-12Т19:35:55+03:00",
    • "expirationDate": "2024-08-12Т20:35:55+03:00",
    • "status": "PAID",
    • "senderPaymentPurpose": "Какое-то назначение платежа",
    • "extra": {
      • "additionalInfo": "testing operation"
      },
    • "qr": {},
    • "payment": {
      • "id": 123456789012345680,
      • "sbpTransactionId": "PMSHT0BYVSYE7LDXMCXJSGIUHJLQWZXY",
      • "status": {
        • "value": "SUCCESS",
        • "date": "2024-06-12Т19:36:55+03:00"
        },
      • "amount": 8573.79,
      • "totalTaxAmount": 2.41,
      • "sender": {
        • "legalName": "ООО Ромашка",
        • "inn": 123456789012,
        • "bank": {
          • "id": 100000000007,
          • "name": "Райффайзенбанк",
          • "bic": 44525700
          }
        }
      }
    }
}

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

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

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

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

Responses

Response Schema: application/json
callbackUrl
required
string

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

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

Реестр

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

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

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

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

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

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