Raiff logo
API docs by Redocly

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

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

Кассовая ссылка для торговых точек

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

Для приема платежей с использованием кассовой ссылки отлично подойдут Платежные таблички Банка, либо же переносное устройство Pay-Point.

После получения Платежной таблички либо Pay-Point, устройство следует установить рядом с кассой, выполнить [Привязку QR-кода к мерчанту] по API либо Привязку QR-кода к мерчанту через интерфейс в Онлайн-Банке.

Далее необходимо сохранить настройки для работы с кассовой ссылкой на кассе для дальнейшей активации QR-кода и приема платежей со стороны кассы.

Параметры, необходимые для сохранения в кассу для корректной работы по протоколу кассовой ссылки:

Параметр Описание параметра
qrId Идентификатор QR-кода
publicId Идентификатор мерчанта
secretKey Ключ, необходимый для авторизации в сервисе Банка при отправке запросов по API

После формирования корзины касса должна отправить [Запрос на создание заказа] для активации QR-кода и получить статус оплаты после ее совершения плательщиком.

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

На схеме ниже представлен сценарий работы с кассовой ссылкой СБП.

Платежная форма для сайта

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

Динамический QR

Динамический QR-код или QRDynamic - вид QR-кода, который хорошо подходит для приема платежей в онлайне (мобильные приложения / сайт), а также в торговой точке.

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

Для корректной работы с кассовой ссылкой рекомендуется поддержать API протокол динамического QR-кода.

На схеме ниже представлен сценарий формирования динамического QR-кода и последующего приема платежа с получением необходимой информации в систему мерчанта.

Подписки

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

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

Подписки с оплатой

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

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

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

Подписки с автоматическим списанием

Механизм подписок также поддерживает регулярные автоматические списания, которые банк проводит в указанную дату в 10:00 или 13:00 по московскому времени. На данный момент поддерживаются только ежемесячные списания. При неуспешной оплате в 10:00 производится еще одна попытка в 13:00 того же дня, при повторной ошибке будет еще по две попытки в последующие дни в то же время. Неуспешность платежа не ведет к отмене подписки.

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

Уведомления о платежах можно получать в виде callback-уведомлений. Деактивировать подписку можно с помощью метода [Отмена подписки].

Разделение платежа

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

Готовые решения

Список готовых решений вы можете посмотреть по ссылке.

Описание API

Bзаимодействие осуществляется по протоколу HTTP с использованием методов POST GET PUT DELETE.

API всегда возвращает ответ в формате JSON, независимо от типа запроса.

Авторизация

Запросы, связанные с получением данных по платежу и управлением платежами, авторизуются посредством секретного ключа API secretKey. Параметр авторизации указывается в заголовке Authorization, значение которого формируется как Bearer secretKey.

Для получения тестовых данных для интеграции необходимо заполнить анкету на pay.raif.ru.

Посмотреть боевой publicId и сгенерировать secretKey можно в Онлайн Банке, либо Личном Кабинете.

Инстуркции по формированию secretKey можно посмотреть в Справочном Центре:

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

Мы рекомендуем создавать одного мерчанта на ЮЛ и, соответственно, все его торговые точки. Это избавит от необходимости:

  • хранить справочник мерчантов с соотношением с вашими торговыми точками
  • хранить большое количество секретных ключей и проводить их индивидуальную настройку для каждой торговой точки по отдельности
  • регистрировать новых мерчантов при открытии новых торговых точек ЮЛ
  • проводить возвраты только в той торговой точке, где была произведена оплата
  • строить сложную отчетность по разным мерчантам
  • распределять QR по разным мерчантам (в случае работы с QRVariable)

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

При работе в мобильной версии сайта или приложении мы рекомендуем использовать платежную форму Райффайзенбанка.

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

Для реализации виджета, необходимо использовать [API Виджета СБП].

Или вы можете воспользоваться нашими SDK:

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

Для полного цикла тестирования Райффайзенбанк предоставляет возможность использования демо-приложения для оплаты QR-кода от имени покупателя: WEB-приложение для оплаты по QR-коду

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

Приложения банков не будут работать для оплаты QR-кодов в тестовой среде

Динамический и статический QR

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

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

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

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

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

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

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

Request Body schema: application/json
required
qrType
required
string

QRDynamic создается под каждую продажу.
Такой QR можно оплатить только один раз, сумма зашивается сразу в QR.

account
number <= 20

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

additionalInfo
string (AdditionalInfo) <= 140 characters ^(?=.*\S)[A-Za-zА-Яа-яЁё0-9 !"#$%''()*+,\-./:...

Дополнительная информация.
Может быть доступна для пользователя в зависимости от банка, назначение платежа плательщика. Попадает в реестр в колонку "Комментарий". Не может быть пустым или содержать только пробелы. Может содержать:
• Символы латиницы (A–Z и a–z)
• Символы кириллицы (А-Я и а-я)
• Цифры 0-9
• Спецсимволы: пробел и !, ", #, $, %, ', (, ), *, +, ,, -, ., /, :, ;, =, >, ?, @, [, \, ], ^, _, {, |, }, ~,№

amount
required
number > 0

Сумма в рублях. Для копеек доступно два знака после точки.

currency
string = 3 characters
Value: "RUB"

Валюта платежа. Если не заполнено, то автоматически указывается значение RUB.

order
required
string (OrderId) ^[A-Za-z0-9-_.]+$

Идентификатор заказа. Рекомендуем использовать длинный формат без возможности перебора, например, использовать формат UUID v4

paymentDetails
string (PaymentDetails) ^(?=.*\S)[A-Za-zА-Яа-яЁё0-9 !"#$%''()*+,\-./:...

Назначение платежа. Отображается в выписке. Может содержать:

  • Символы латиницы (A–Z и a–z)
  • Символы кириллицы (А-Я и а-я)
  • Цифры 0-9
  • Спецсимволы: пробел и !, ", #, $, %, ', (, ), *, +, ,, -, ., /, :, ;, =, >, ?, @, [, \, ], ^, _, {, |, }, ~
  • Спецсимвол №
qrExpirationDate
string <date-time> (ExpirationDate)

Срок действия
Может содержать точную дату и время, например 2025-01-10T20:10:00+03:00 или количество минут в формате +nM, где n - количество минут. Например, для формирования QR на 2 минуты можно передать: '+2M'.
Параметр не может быть меньше текущей даты и времени. Не может быть меньше 1 минуты. Максимальное значение - 90 суток. Если параметр не передан, то по умолчанию QR будет действителен 3 суток

sbpMerchantId
required
string <= 12 characters

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

redirectUrl
string (RedirectUrl) ^[A-Za-z][A-Za-z0-9]*://\S+$

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

  • Допускается использование схемы http или https, за которой следует :// и последовательность символов без пробелов.
  • Допускается использование схемы, начинающейся с буквы латинского алфавита и содержащей цифры, за которыми следует :// и непробельная последовательность символов.
qrDescription
string <= 32 characters

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

object (Subscription)

Данные для оформления подписки. Результат подписки зависит от плательщика.

object (Extra)

Дополнительные поля для свободного заполнения по принципу key-value
В extra рекомендуется передавать параметры apiClient и apiClientVersion. Данная информация позволит Банку определять клиентское ПО, исправлять ошибки и улучшать сервис

Responses

Request samples

Content type
application/json
Example
{
  • "account": 40700000000000000000,
  • "additionalInfo": "Доп. информация",
  • "amount": 1110.11,
  • "currency": "RUB",
  • "order": "1-22-333",
  • "paymentDetails": "Назначение платежа",
  • "qrType": "QRDynamic",
  • "extra": {
    },
  • "qrExpirationDate": "2023-07-22T09:14:38+03:00",
  • "sbpMerchantId": "MA0000000552",
  • "redirectUrl": "https://bfkh.ru/",
  • "qrDescription": "QR для оплаты заказа"
}

Response samples

Content type
application/json
Example

Отмена QR

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

Authorizations:
secretKey
path Parameters
qrId
required
string

Идентификатор QR кода

Responses

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

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

Authorizations:
secretKey
path Parameters
qrId
required
string

Идентификатор QR кода

Responses

Response samples

Content type
application/json
Example

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

Метод позволяет получить информацию по платежу по QR-коду. Метод не используется для QRVariable.

Authorizations:
secretKey
path Parameters
qrId
required
string

Идентификатор QR кода

Responses

Response samples

Content type
application/json
{
  • "additionalInfo": "Доп. информация",
  • "paymentPurpose": "Назначение платежа",
  • "amount": 1110.11,
  • "code": "SUCCESS",
  • "createDate": "2020-01-31T09:14:38.107227+03:00",
  • "currency": "RUB",
  • "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",
  • "extra": {
    }
}

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

Метод позволяет выполнить возврат по заказу.
Метод также позволяет провести возврат плательщику в другой банк. Поддерживаются как полный, так и частичный возвраты.

Authorizations:
secretKey
path Parameters
orderId
required
string

Идентификатор заказа

refundId
required
string

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

Request Body schema: application/json
required
amount
required
number

Сумма в рублях. Для копеек доступно два знака после точки.

paymentDetails
string (PaymentDetails) ^(?=.*\S)[A-Za-zА-Яа-яЁё0-9 !"#$%''()*+,\-./:...

Назначение платежа. Отображается в выписке. Может содержать:

  • Символы латиницы (A–Z и a–z)
  • Символы кириллицы (А-Я и а-я)
  • Цифры 0-9
  • Спецсимволы: пробел и !, ", #, $, %, ', (, ), *, +, ,, -, ., /, :, ;, =, >, ?, @, [, \, ], ^, _, {, |, }, ~
  • Спецсимвол №
object

Данные плательщика. Необходимо заполнять, если требуется выполнить возврат в другой банк.

Responses

Request samples

Content type
application/json
Example
{
  • "amount": 10,
  • "paymentDetails": "Назначение платежа"
}

Response samples

Content type
application/json
Example
{
  • "amount": 22,
  • "status": {
    }
}

Получение статуса возврата

Метод позволяет получить статус по возврату.

Authorizations:
secretKey
path Parameters
orderId
required
string

Идентификатор заказа

refundId
required
string

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

Responses

Response samples

Content type
application/json
Example
{
  • "amount": 22,
  • "status": {
    }
}

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

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

Authorizations:
secretKey
Request Body schema: application/json
required
amount
required
number > 0

Сумма в рублях. Для копеек доступно два знака после точки.Сумма возврата в рублях

order
required
string (OrderId) ^[A-Za-z0-9-_.]+$

Идентификатор заказа. Рекомендуем использовать длинный формат без возможности перебора, например, использовать формат UUID v4

paymentDetails
string (PaymentDetails) ^(?=.*\S)[A-Za-zА-Яа-яЁё0-9 !"#$%''()*+,\-./:...

Назначение платежа. Отображается в выписке. Может содержать:

  • Символы латиницы (A–Z и a–z)
  • Символы кириллицы (А-Я и а-я)
  • Цифры 0-9
  • Спецсимволы: пробел и !, ", #, $, %, ', (, ), *, +, ,, -, ., /, :, ;, =, >, ?, @, [, \, ], ^, _, {, |, }, ~
  • Спецсимвол №
refundId
required
string [ 1 .. 40 ] characters ^[A-Za-z0-9-_.]+$

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

transactionId
number

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

Responses

Request samples

Content type
application/json
{
  • "amount": 150,
  • "order": "test_order_007",
  • "paymentDetails": "Test",
  • "refundId": "test_refundId_007",
  • "transactionId": 41
}

Response samples

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

Получение списка банков для возвратов

Получение списка банков, принимающих возвраты по СБП.

Authorizations:
secretKey

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    }
]

Кассовая ссылка

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

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

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

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

Привязка кассовой ссылки

Метод позволяет привязать драфт кассовой ссылки к мерчанту. Метод также позволяет перепривязать кассовую ссылку между мерчантами, либо изменить параметры QR-кода у текущего мерчанта. Перед перепривязкой QR-кода, необходима настройка со стороны Банка, для настройки необходимо написать на ecom@raiffeisen.ru с указанием мерчантов, между которыми будет осуществляться перепривязка QR-кодов.

Authorizations:
secretKey
path Parameters
qrId
required
string

Идентификатор QR кода

Request Body schema: application/json
account
string

Счет для зачисления

redirectUrl
string (RedirectUrl) ^[A-Za-z][A-Za-z0-9]*://\S+$

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

  • Допускается использование схемы http или https, за которой следует :// и последовательность символов без пробелов.
  • Допускается использование схемы, начинающейся с буквы латинского алфавита и содержащей цифры, за которыми следует :// и непробельная последовательность символов.
qrDescription
string <= 32 characters

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

Responses

Request samples

Content type
application/json
{
  • "account": "40700000000000000000",
  • "redirectUrl": "string",
  • "qrDescription": "QR на главной кассе"
}

Response samples

Content type
application/json
{}

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

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

Authorizations:
secretKey
Request Body schema: application/json
required
id
string [ 1 .. 40 ] characters ^[A-Za-z0-9-_.]+$

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

amount
number > 0

Сумма в рублях. Для копеек доступно два знака после точки.

comment
string (OrderComment) <= 140 characters ^(?=.*\S)[A-Za-zА-Яа-яЁё0-9 !"#$%''()*+,\-./:...

Комментарий. Доступен в реестрах и Онлайн-Банке. Не может быть пустым или содержать только пробелы. Может содержать:
• Символы латиницы (A–Z и a–z)
• Символы кириллицы (А-Я и а-я)
• Цифры 0-9
• Спецсимволы: пробел и !, ", #, $, %, ', (, ), *, +, ,, -, ., /, :, ;, =, >, ?, @, [, \, ], ^, _, {, |, }, ~
• Спецсимвол №

object (Extra)

Дополнительные поля для свободного заполнения по принципу key-value
В extra рекомендуется передавать параметры apiClient и apiClientVersion. Данная информация позволит Банку определять клиентское ПО, исправлять ошибки и улучшать сервис

expirationDate
string <date-time> (ExpirationDate)

Срок действия
Может содержать точную дату и время, например 2025-01-10T20:10:00+03:00 или количество минут в формате +nM, где n - количество минут. Например, для формирования QR на 2 минуты можно передать: '+2M'.
Параметр не может быть меньше текущей даты и времени. Не может быть меньше 1 минуты. Максимальное значение - 90 суток. Если параметр не передан, то по умолчанию QR будет действителен 3 суток

object

Блок с данными QR-кода
Объект заполняется, если необходимо связать заказ с QR-кодом

Responses

Request samples

Content type
application/json
{
  • "id": "c5b3fd07-c66b-4f11-a8a2-1cc5d319f9e3",
  • "amount": 1000.1,
  • "comment": "Шоколадный торт",
  • "extra": {
    },
  • "expirationDate": "2023-01-24T11:14:38+03:00",
  • "qr": {
    }
}

Response samples

Content type
application/json
{
  • "id": "c5b3fd07-c66b-4f11-a8a2-1cc5d319f9e3",
  • "amount": 1000.1,
  • "comment": "Шоколадный торт",
  • "extra": {
    },
  • "status": {
    },
  • "expirationDate": "2022-01-24T11:15:22.000Z",
  • "qr": {
    }
}

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

Метод позволяет получить статус заказа по его номеру. Опрос статуса заказа рекомендуется проводить раз в 2 секунды. При работе в штатном режиме заказ переводится в статус оплаченного в течение 15 секунд с момента оплаты.

Authorizations:
secretKey
path Parameters
orderId
required
string

Идентификатор заказа

Responses

Response samples

Content type
application/json
{
  • "id": "c5b3fd07-c66b-4f11-a8a2-1cc5d319f9e3",
  • "amount": 1000.1,
  • "comment": "Шоколадный торт",
  • "extra": {
    },
  • "status": {
    },
  • "expirationDate": "2022-01-24T11:15:22.000Z",
  • "qr": {
    }
}

Отмена заказа

Данный метод позволяет отменить заказ, если он не был оплачен. После отмены заказ будет недоступен для оплаты.

Authorizations:
secretKey
path Parameters
orderId
required
string

Идентификатор заказа

Responses

Response samples

Content type
application/json
Example
{
  • "code": "ERROR.INVALID_REQUEST",
  • "message": "Недопустимый идентификатор заказа"
}

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

Метод позволяет выполнить возврат по заказу.
Метод также позволяет провести возврат плательщику в другой банк. Поддерживаются как полный, так и частичный возвраты.

Authorizations:
secretKey
path Parameters
orderId
required
string

Идентификатор заказа

refundId
required
string

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

Request Body schema: application/json
required
amount
required
number

Сумма в рублях. Для копеек доступно два знака после точки.

paymentDetails
string (PaymentDetails) ^(?=.*\S)[A-Za-zА-Яа-яЁё0-9 !"#$%''()*+,\-./:...

Назначение платежа. Отображается в выписке. Может содержать:

  • Символы латиницы (A–Z и a–z)
  • Символы кириллицы (А-Я и а-я)
  • Цифры 0-9
  • Спецсимволы: пробел и !, ", #, $, %, ', (, ), *, +, ,, -, ., /, :, ;, =, >, ?, @, [, \, ], ^, _, {, |, }, ~
  • Спецсимвол №
object

Данные плательщика. Необходимо заполнять, если требуется выполнить возврат в другой банк.

Responses

Request samples

Content type
application/json
Example
{
  • "amount": 10,
  • "paymentDetails": "Назначение платежа"
}

Response samples

Content type
application/json
Example
{
  • "amount": 22,
  • "status": {
    }
}

Получение статуса возврата

Метод позволяет получить статус по возврату.

Authorizations:
secretKey
path Parameters
orderId
required
string

Идентификатор заказа

refundId
required
string

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

Responses

Response samples

Content type
application/json
Example
{
  • "amount": 22,
  • "status": {
    }
}

Получение списка банков для возвратов

Получение списка банков, принимающих возвраты по СБП.

Authorizations:
secretKey

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    }
]

Подписки

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

Посмотреть клиентский путь можно с помощью нашей Демо страницы подписок

Для реализации возможны два сценария:

  • отдельно подписка с последующими платежами

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

  • подписка с оплатой

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

Произвести подписку могут клиенты банков, поддержавших механизм подписки. Произвести оплату возможно из приложения любого банка.

Список банков, поддержавших механизм подписки.

Виджеты

Для размещения виджета у себя на сайте необходимо:

  • cкопировать код виджета (iframe)
  • открыть HTML код вашей страницы для редактирования
  • вставить код виджета в необходимое место страницы
  • сохранить HTML код страницы и обновить ее на сайте

Параметры виджета

Параметр Описание Значение
src* URL-адрес встраиваемой страницы Описано ниже
width* Ширина виджета
Может быть задана клиентом, но максимальный размер не должен превышать 728 пикселей		 от 280 до 728 пикселей
height* Высота виджета
Фиксированное значение		 280 пикселей
style* Стиль для корректного отображения рамки виджета "border: 0; border-radius: 16px"
allowtransparency* Прозрачный фон виджета true
scrolling* Полосы прокрутки. Не используются no
frameborder* Рамка с эффектом трехмерности. Не отображается 0

Параметры URL-адреса встраиваемой страницы

Параметр Описание Значение
HOST* Хост * https://pay.raif.ru (продовый хост)
* https://pay-test.raif.ru (тестовый хост)
publicId* Идентификатор, который используется для открытия платежной формы и не является конфиденциальным
subscriptionPurpose* Цель подписки (отображается на виджете)
logo Ссылка на логотип клиента (отображается на виджете)
widgetType* Тип виджета * CHARITY (благотворительность)
* PAYMENT (оплата)
buttonColor* Цвет кнопки Передавать в формате hex без символа #
Например, цвет #774098 нужно передать как buttonColor=774098
textButtonColor* Цвет текста внутри кнопки Передавать в формате hex без символа #
offer Ссылка на оферту клиента
Если параметр не передан, то в виджете отобразится только ссылка на условия платежа и подключения подписки		 * Параметр не передан, отобразится текст:
"Оплачивая, вы соглашаетесь с условиями"

* Параметр передан, отобразится текст:
"Оплачивая, вы соглашаетесь с условиями и офертой"

Пример iframe для виджета на тестовой среде: 

<iframe src="https://pay-test.raif.ru/widgets/?publicId=000001780049001-80049001&subscriptionPurpose=%D0%91%D0%BB%D0%B0%D0%B3%D0%BE%D1%82%D0%B2%D0%BE%D1%80%D0%B8%D1%82%D0%B5%D0%BB%D1%8C%D0%BD%D0%BE%D0%B5%20%D0%BF%D0%BE%D0%B6%D0%B5%D1%80%D1%82%D0%B2%D0%BE%D0%B2%D0%B0%D0%BD%D0%B8%D0%B5&logo=https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcTqiwtWhVXbOj0gImTuuRHXuDre7gr-MEdQOpsJU9pNy2TRhYDyIuqkPIzZ_0RSyDE2G-M&usqp=CAU&widgetType=CHARITY&buttonColor=774098&textButtonColor=FFFFFF&offer=https://bfkh.ru/oferta_bfkh.pdf" width="630" height="280" style="border: 0; border-radius: 16px" allowtransparency="true" scrolling="no" frameborder="0"></iframe>
Подставьте в iframe продовый хост, также укажите данные своей компании в параметрах URL-адреса встраиваемой страницы и интегрируйте к себе на сайт.

Создание QR для подписки

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

Request Body schema: application/json
required
id
string <= 40 characters ^[A-Za-z0-9-_.]+$

Идентификатор подписки на стороне партнера. Рекомендуем использовать длинный формат без возможности перебора, например, использовать формат UUID v4

subscriptionPurpose
required
string <= 140 characters ^[A-Za-zА-Яа-я0-9 ()!@\[\]#+=_\|.,-]+$

Описание подписки
Может содержать:

  • Символы латиницы (A-Z и a-z)
  • Символы кириллицы (А-Я и а-я)
  • Цифры 0-9
  • Спецсимволы: (, ), !, @, [, ], #, +, =, -, |, ., ,
sbpMerchantId
required
string <= 12 characters

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

redirectUrl
string (RedirectUrl) ^[A-Za-z][A-Za-z0-9]*://\S+$

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

  • Допускается использование схемы http или https, за которой следует :// и последовательность символов без пробелов.
  • Допускается использование схемы, начинающейся с буквы латинского алфавита и содержащей цифры, за которыми следует :// и непробельная последовательность символов.
object (SubscriptionAutoCharge)

Данные автоматического списания по подписке. Объект передается, если по подписке необходимо взимать деньги на регуряной основе. Используется как альтернатива методу списания по запросу

object (Extra)

Дополнительные поля для свободного заполнения по принципу key-value
В extra рекомендуется передавать параметры apiClient и apiClientVersion. Данная информация позволит Банку определять клиентское ПО, исправлять ошибки и улучшать сервис

Responses

Request samples

Content type
application/json
Example
{
  • "id": "120059",
  • "subscriptionPurpose": "Подписка на услуги",
  • "redirectUrl": "https://bfkh.ru/",
  • "sbpMerchantId": "MA0000000552"
}

Response samples

Content type
application/json
Example
{}

Получение информации по подписке

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

Authorizations:
secretKey
path Parameters
subscriptionId
required
string

Идентификатор подписки

Responses

Response samples

Content type
application/json
Example
{}

Отмена подписки

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

Authorizations:
secretKey
path Parameters
subscriptionId
required
string

Идентификатор подписки

Responses

Response samples

Content type
application/json
Example
{
  • "code": "ERROR.INVALID_REQUEST",
  • "message": "Недопустимый идентификатор заказа"
}

Запрос на совершение платежа по подписке

Метод позволяет создать заказ и инициировать списание со счета клиента в рамках созданной подписки. Метод предназначен для списания средств по подписке, у которой не настроено автоматическое списание autoCharge. При успешном списании будет направлено стандартное уведомление об оплате.
Для возврата средств по подписке используется метод [Оформление возврата по платежу].

Authorizations:
secretKey
path Parameters
subscriptionId
required
string

Идентификатор подписки

Request Body schema: application/json
account
number

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

additionalInfo
required
string (AdditionalInfo) <= 140 characters ^(?=.*\S)[A-Za-zА-Яа-яЁё0-9 !"#$%''()*+,\-./:...

Дополнительная информация.
Может быть доступна для пользователя в зависимости от банка, назначение платежа плательщика. Попадает в реестр в колонку "Комментарий". Не может быть пустым или содержать только пробелы. Может содержать:
• Символы латиницы (A–Z и a–z)
• Символы кириллицы (А-Я и а-я)
• Цифры 0-9
• Спецсимволы: пробел и !, ", #, $, %, ', (, ), *, +, ,, -, ., /, :, ;, =, >, ?, @, [, \, ], ^, _, {, |, }, ~,№

amount
required
number

Сумма в рублях. Для копеек доступно два знака после точки.

currency
required
string
Value: "RUB"

Валюта платежа.

order
string <= 40 characters ^[A-Za-z0-9-_.]+$

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

paymentDetails
string (PaymentDetails) ^(?=.*\S)[A-Za-zА-Яа-яЁё0-9 !"#$%''()*+,\-./:...

Назначение платежа. Отображается в выписке. Может содержать:

  • Символы латиницы (A–Z и a–z)
  • Символы кириллицы (А-Я и а-я)
  • Цифры 0-9
  • Спецсимволы: пробел и !, ", #, $, %, ', (, ), *, +, ,, -, ., /, :, ;, =, >, ?, @, [, \, ], ^, _, {, |, }, ~
  • Спецсимвол №
Array of objects (Splits)

Блок данных для работы со сплитованием

Responses

Request samples

Content type
application/json
Example
{
  • "account": 40700000000000000000,
  • "additionalInfo": "Доп. информация",
  • "amount": 1110,
  • "currency": "RUB",
  • "order": "1-22-333",
  • "paymentDetails": "Назначение платежа"
}

Response samples

Content type
application/json
{
  • "additionalInfo": "Доп. информация",
  • "paymentDetails": "Назначение платежа",
  • "amount": 1110,
  • "currency": "RUB",
  • "order": "282a60f8-dd75-4286-bde0-af321dd081b3",
  • "paymentStatus": "IN_PROGRESS",
  • "qrId": "AD100051KNSNR64I98CRUJUASC9M72QT",
  • "sbpMerchantId": "MA0000000552",
  • "splits": [
    ]
}

Проверка статуса платежа по подписке

Метод позволяет получить данные по платежу, сделанному по подписке

Authorizations:
secretKey
path Parameters
subscriptionId
required
string

Идентификатор подписки

orderId
required
string

Идентификатор заказа

Responses

Response samples

Content type
application/json
{
  • "additionalInfo": "Доп. информация",
  • "paymentDetails": "Назначение платежа",
  • "amount": 1110,
  • "currency": "RUB",
  • "order": "282a60f8-dd75-4286-bde0-af321dd081b3",
  • "paymentStatus": "IN_PROGRESS",
  • "qrId": "AD100051KNSNR64I98CRUJUASC9M72QT",
  • "sbpMerchantId": "MA0000000552",
  • "splits": [
    ]
}

Разделение платежа

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

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

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

Денежные средства распределяются на счета контрагентов на следующий день после совершения платежа. Всю сумму платежа можно зачислить как на один счет контрагента, так и на несколько счетов.

Запрос создания заказа

Метод позволяет создать заказ с привязкой к существующему кассовой ссылке QRVariable или с созданием нового динамического QR-кода QRDynamic. Также с помощью данного метода вы можете сгенерировать QR код для оплаты с подпиской.

Authorizations:
secretKey
path Parameters
publicId
required
string

Идентификатор мерчанта

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

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

amount
required
number <float> > 0

Сумма заказа

comment
string (OrderComment) <= 140 characters ^(?=.*\S)[A-Za-zА-Яа-яЁё0-9 !"#$%''()*+,\-./:...

Комментарий. Доступен в реестрах и Онлайн-Банке. Не может быть пустым или содержать только пробелы. Может содержать:
• Символы латиницы (A–Z и a–z)
• Символы кириллицы (А-Я и а-я)
• Цифры 0-9
• Спецсимволы: пробел и !, ", #, $, %, ', (, ), *, +, ,, -, ., /, :, ;, =, >, ?, @, [, \, ], ^, _, {, |, }, ~
• Спецсимвол №

object (Extra)

Дополнительные поля для свободного заполнения по принципу key-value
В extra рекомендуется передавать параметры apiClient и apiClientVersion. Данная информация позволит Банку определять клиентское ПО, исправлять ошибки и улучшать сервис

expirationDate
string <date-time> (ExpirationDate)

Срок действия
Может содержать точную дату и время, например 2025-01-10T20:10:00+03:00 или количество минут в формате +nM, где n - количество минут. Например, для формирования QR на 2 минуты можно передать: '+2M'.
Параметр не может быть меньше текущей даты и времени. Не может быть меньше 1 минуты. Максимальное значение - 90 суток. Если параметр не передан, то по умолчанию QR будет действителен 3 суток

Array of objects (Splits)

Блок данных для работы со сплитованием

CreateOrderQrVariableRequest (object) or CreateOrderQrDynamicRequest (object)

Responses

Request samples

Content type
application/json
Example
{
  • "id": "5d5d52a0-2c7a-4a41-9d9c-c0f91f5ce266",
  • "amount": 432.19,
  • "comment": "Комментарий к заказу",
  • "extra": {
    },
  • "expirationDate": "2025-05-01T16:34:09+03:00",
  • "splits": [
    ],
  • "qr": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "amount": 432.19,
  • "comment": "Тестовый комментарий",
  • "extra": {
    },
  • "status": {
    },
  • "expirationDate": "2019-08-24T14:15:22Z",
  • "qr": {},
  • "splits": [
    ]
}

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

Метод позволяет создать или изменить заказ.

Authorizations:
secretKey
path Parameters
publicId
required
string

Идентификатор мерчанта

orderId
required
string

Идентификатор заказа

Request Body schema: application/json
required
amount
required
number <float>

Сумма заказа

comment
string (OrderComment) <= 140 characters ^(?=.*\S)[A-Za-zА-Яа-яЁё0-9 !"#$%''()*+,\-./:...

Комментарий. Доступен в реестрах и Онлайн-Банке. Не может быть пустым или содержать только пробелы. Может содержать:
• Символы латиницы (A–Z и a–z)
• Символы кириллицы (А-Я и а-я)
• Цифры 0-9
• Спецсимволы: пробел и !, ", #, $, %, ', (, ), *, +, ,, -, ., /, :, ;, =, >, ?, @, [, \, ], ^, _, {, |, }, ~
• Спецсимвол №

object (Extra)

Дополнительные поля для свободного заполнения по принципу key-value
В extra рекомендуется передавать параметры apiClient и apiClientVersion. Данная информация позволит Банку определять клиентское ПО, исправлять ошибки и улучшать сервис

expirationDate
string <date-time> (ExpirationDate)

Срок действия
Может содержать точную дату и время, например 2025-01-10T20:10:00+03:00 или количество минут в формате +nM, где n - количество минут. Например, для формирования QR на 2 минуты можно передать: '+2M'.
Параметр не может быть меньше текущей даты и времени. Не может быть меньше 1 минуты. Максимальное значение - 90 суток. Если параметр не передан, то по умолчанию QR будет действителен 3 суток

Array of objects (Splits)

Блок данных для работы со сплитованием

CreateOrderQrVariableRequest (object) or CreateOrderQrDynamicRequest (object)

Responses

Request samples

Content type
application/json
Example
{
  • "amount": 432.19,
  • "comment": "Комментарий к заказу",
  • "extra": {
    },
  • "expirationDate": "2025-05-01T16:34:09+03:00",
  • "splits": [
    ],
  • "qr": {
    }
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "amount": 432.19,
  • "comment": "Тестовый комментарий",
  • "extra": {
    },
  • "status": {
    },
  • "expirationDate": "2019-08-24T14:15:22Z",
  • "qr": {},
  • "splits": [
    ]
}

Получения статуса заказа

Метод позволяет получить статус заказа по его номеру. Опрос статуса заказа рекомендуется проводить раз в 2 секунды. При работе в штатном режиме заказ переводится в статус оплаченного в течение 15 секунд с момента оплаты.

Authorizations:
secretKey
path Parameters
publicId
required
string

Идентификатор мерчанта

orderId
required
string

Идентификатор заказа

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "amount": 432.19,
  • "comment": "Тестовый комментарий",
  • "extra": {
    },
  • "status": {
    },
  • "expirationDate": "2019-08-24T14:15:22Z",
  • "qr": {},
  • "splits": [
    ]
}

Отмена заказа

Данный метод позволяет отменить заказ, если он не был оплачен. После отмены заказ будет недоступен для оплаты.

Authorizations:
secretKey
path Parameters
publicId
required
string

Идентификатор мерчанта

orderId
required
string

Идентификатор заказа

Responses

Response samples

Content type
application/json
Example
{
  • "code": "ERROR.INVALID_REQUEST",
  • "message": "Недопустимый идентификатор заказа"
}

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

Метод позволяет выполнить возврат по заказу. Метод также позволяет провести возврат плательщику в другой банк. Поддерживаются как полный, так и частичный возвраты.

Authorizations:
secretKey
path Parameters
orderId
required
string

Идентификатор заказа

publicId
required
string

Идентификатор мерчанта

Request Body schema: application/json
required
id
string <= 40 characters ^[A-Za-z0-9-_.]+$

Идентификатор возврата

amount
required
number <float>

Сумма возврата

paymentDetails
string (PaymentDetails) ^(?=.*\S)[A-Za-zА-Яа-яЁё0-9 !"#$%''()*+,\-./:...

Назначение платежа. Отображается в выписке. Может содержать:

  • Символы латиницы (A–Z и a–z)
  • Символы кириллицы (А-Я и а-я)
  • Цифры 0-9
  • Спецсимволы: пробел и !, ", #, $, %, ', (, ), *, +, ,, -, ., /, :, ;, =, >, ?, @, [, \, ], ^, _, {, |, }, ~
  • Спецсимвол №
Array of objects (Splits)

Блок данных для работы со сплитованием

object

Объект передается, если требуется сделать возврат в другой банк или на другой номер

Responses

Request samples

Content type
application/json
Example
{
  • "id": "348230ad-2a8d-4976-af4f-8603d11cba8c",
  • "amount": 432.21,
  • "paymentDetails": "Возврат за обувь",
  • "splits": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "348230ad-2a8d-4976-af4f-8603d11cba8c",
  • "amount": 432.21,
  • "paymentDetails": "string",
  • "customer": {
    },
  • "splits": [
    ],
  • "status": {
    }
}

Получение статуса возврата по заказу

Метод позволяет получить статус по возврату.

Authorizations:
secretKey
path Parameters
publicId
required
string

Идентификатор мерчанта

orderId
required
string

Идентификатор заказа

refundId
required
string

Идентификатор возврата

Responses

Response samples

Content type
application/json
{
  • "id": "348230ad-2a8d-4976-af4f-8603d11cba8c",
  • "amount": 432.21,
  • "paymentDetails": "string",
  • "customer": {
    },
  • "splits": [
    ],
  • "status": {
    }
}

Получение списка банков для возвратов

Получение списка банков, принимающих возвраты по СБП.

Authorizations:
secretKey

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    }
]

Уведомления

Для информирования ТСП о проведенных платежах, возвратах и изменениях статусов подписок могут использоваться HTTP-уведомления на адрес, указанный в его настройках.

Боевой адрес можно указать в личном кабинете во вкладке "Прием платежей".

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

Для партнёра уведомление представляет собой входящий POST-запрос, который использует JSON-структуру.

Уведомление считается принятым, если получатель ответил на запрос кодом HTTP 200.

Ответы с любыми другими HTTP-кодами будут считаться невалидными. Повторные попытки отправки будут проводиться в течение суток с нарастающим интервалом.

Для проверки подлинности уведомлений к данным добавляется подпись в заголовке x-api-signature-sha256, полученная на основе общего секретного ключа и контрольной строки, зашифрованной с помощью HMAC-SHA-256.

Тип уведомления Шаблон проверки
Уведомление о платеже по QRStatic и QRDynamic amount|sbpMerchantId|order|paymentStatus|transactionDate
Уведомление об оплате заказа amount|publicId|order|transaction.status.value|transaction.status.date
Уведомление о возврате amount|publicId|refund.id|status.value|status.date.
Уведомление об изменении состояния подписки public|id|status|date

Уведомления отправляются с IP 193.28.44.23

Уведомление об оплате заказа Webhook

Для проверки подлинности уведомления к данным добавляется подпись в заголовке, полученная на основе общего секретного ключа и контрольной строки с помощью HMAC-SHA-256.

header Parameters
X-Api-Signature-SHA256
required
string

Заполняется подписью, полученной алгоритмом HMAC-SHA-256 с использованием выбранного секретного ключа и контрольной строки

Request Body schema: application/json
event
string
Value: "payment"

Тип сообщения

object

Request samples

Content type
application/json
{
  • "event": "payment",
  • "transaction": {
    }
}

Уведомление о платеже по QRStatic и QRDynamic Webhook

Для проверки подлинности уведомления к данным добавляется подпись в заголовке, полученная на основе общего секретного ключа и контрольной строки с помощью HMAC-SHA-256.

header Parameters
X-Api-Signature-SHA256
required
string

Заполняется подписью, полученной алгоритмом HMAC-SHA-256 с использованием выбранного секретного ключа и контрольной строки

Request Body schema: application/json
transactionId
number

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

qrId
string <= 32 characters

Уникальный идентификатор QR-кода, выданный СБП при запросе генерации QR-кода

sbpMerchantId
string <= 12 characters

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

merchantId
string

Идентификатор ТСП в Райффайзенбанке

amount
number

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

currency
string <= 3 characters

Валюта платежа

transactionDate
string <YYYY-MM-DD ТHH24:MM:SS±HH:MM>

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

paymentStatus
string

Статус проведения платежа

additionalInfo
string (AdditionalInfo) <= 140 characters ^(?=.*\S)[A-Za-zА-Яа-яЁё0-9 !"#$%''()*+,\-./:...

Дополнительная информация.
Может быть доступна для пользователя в зависимости от банка, назначение платежа плательщика. Попадает в реестр в колонку "Комментарий". Не может быть пустым или содержать только пробелы. Может содержать:
• Символы латиницы (A–Z и a–z)
• Символы кириллицы (А-Я и а-я)
• Цифры 0-9
• Спецсимволы: пробел и !, ", #, $, %, ', (, ), *, +, ,, -, ., /, :, ;, =, >, ?, @, [, \, ], ^, _, {, |, }, ~,№

order
string <= 40 characters

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

createDate
string <YYYY-MM-DD ТHH24:MM:SS±HH:MM>

Время формирования заявки

object

Дополнительные поля, переданные в запросе ранее
Если платеж совершен по подписке автоматически, в extra вернется параметр, переданный ранее в запросе на создание подписки или QR

Request samples

Content type
application/json
{
  • "transactionId": 41,
  • "qrId": "AS100032PQ7739G58NCQ457RA2OG82JP",
  • "sbpMerchantId": "MA0000000279",
  • "merchantId": "1780672001",
  • "amount": 10,
  • "currency": "RUB",
  • "transactionDate": "2020-01-15T16:01:49.043924+03:00",
  • "paymentStatus": "SUCCESS",
  • "additionalInfo": "Дополнительная информация",
  • "order": "testOrder",
  • "createDate": "2020-01-15T13:00:40+03:00",
  • "extra": {
    }
}

Уведомление о возврате Webhook

Для проверки подлинности уведомления к данным добавляется подпись в заголовке, полученная на основе общего секретного ключа и контрольной строки с помощью HMAC-SHA-256.

header Parameters
X-Api-Signature-SHA256
required
string

Заполняется подписью, полученной алгоритмом HMAC-SHA-256 с использованием выбранного секретного ключа и контрольной строки

Request Body schema: application/json
object

Request samples

Content type
application/json
Example
{
  • "refund": {
    }
}

Уведомление об изменении статуса подписки Webhook

Для проверки подлинности уведомления к данным добавляется подпись в заголовке, полученная на основе общего секретного ключа и контрольной строки с помощью HMAC-SHA-256.

header Parameters
X-Api-Signature-SHA256
required
string

Заполняется подписью, полученной алгоритмом HMAC-SHA-256 с использованием выбранного секретного ключа и контрольной строки

Request Body schema: application/json
event
string
Value: "SUBSCRIPTION"

Тип сообщения

object

Request samples

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

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

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

Authorizations:
secretKey
Request Body schema: application/json
callbackUrl
required
string non-empty

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

Реестр

Для настройки отправки реестров на ежедневной, еженедельной или ежемесячной основе следуйте инструкциям по работе в Личном кабинете или Онлайн-Банке.

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

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

Наименование колонки Значение
Мерчант Идентификатор в системе СБП
Дата операции МСК Дата и время проведения операции (МСК)
Тип Тип операции
id заказа Id заказа в системе партнера (order)
id возврата Id возврата в системе партнера (refundId)
Способ оплаты Instant Payment QR
Данные оплаты QR id
id клиента Маскированный код плательщика
Сумма Сумма транзакции
Комиссия Комиссия по транзакции
id операции НСПК Идентификатор операции в системе НСПК
Назначение платежа Назначение платежа (paymentDetails)
Комментарий Комментарий к заказу
Дополнительные поля Дополнительная информация (пока не используется)
id проводки Номер банковской проводки

Пример реестра:
Download CSV

Выписка

Потранзакционнцю выписку можно выгрузить в банк-клиенте в следующих форматах:

Download PDF Download 1C Download XML

В назначении платежа есть системиный префикс: номер проводки, тип операции, идентификатор мерчанта НСПК.

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

Для агрегированного зачисления:

Download PDF Download 1C Download XML

Нарратив для агрегированной проводки можно изменить, обратившись на ecom@raiffeisen.ru. Максимальная длина изменяемого нарратива - 60 символов.

Сверка операций за период

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

Сверка по транзакциям за указанный период

Отчёт по транзакциям за указанный период.
Максимальная глубина запрашиваемых данных не более трёх дней.

Пример запроса:

GET https://pay.raif.ru/api/report/v1/transactions/summary?from=2026-01-15T00%3A00%3A00%2B03%3A00&to=2026-01-16T23%3A59%3A59%2B03%3A00
Authorizations:
secretKey
query Parameters
from
required
string <date-time>
Example: from=2026-01-15T12:00:00+03:00

Дата и время начала выборки.
Параметр должен передаваться в формате URL-encoded. К примеру, значение 2026-01-15T12:00:00+03:00 необходимо привести к формату 2026-01-15T12%3A00%3A00%2B03%3A00.

to
required
string <date-time>
Example: to=2026-01-15T15:00:00+03:00

Дата и время окончания выборки.
Параметр должен передаваться в формате URL-encoded. К примеру, значение 2026-01-15T15:00:00+03:00 необходимо привести к формату 2026-01-15T15%3A00%3A00%2B03%3A00.

qrId
string
Example: qrId=AD1F2CD7212E48FA919AB52EF0AEFB33

Идентификатор QR-кода. Если значение не передано - выгружаются все операции по мерчанту

operationTypes
string
Enum: "Payment" "Refund"

Тип операции. Если значение не передано - выгружаются все типы операций

Responses

Response samples

Content type
application/json
{
  • "sbp": {
    },
  • "card": {
    }
}

Детализированный отчет транзакций за период

Получение детализированного отчёта по транзакциям за указанный период.
Максимальная глубина запрашиваемых данных не более трёх дней.

Пример запроса:

GET https://pay.raif.ru/api/report/v1/transactions?from=2026-01-15T00%3A00%3A00%2B03%3A00&to=2026-01-16T23%3A59%3A59%2B03%3A00
Authorizations:
secretKey
query Parameters
from
required
string <date-time>
Example: from=2026-01-15T12:00:00+03:00

Дата и время начала выборки.
Параметр должен передаваться в формате URL-encoded. К примеру, значение 2026-01-15T12:00:00+03:00 необходимо привести к формату 2026-01-15T12%3A00%3A00%2B03%3A00.

to
required
string <date-time>
Example: to=2026-01-15T15:00:00+03:00

Дата и время окончания выборки.
Параметр должен передаваться в формате URL-encoded. К примеру, значение 2026-01-15T15:00:00+03:00 необходимо привести к формату 2026-01-15T15%3A00%3A00%2B03%3A00.

qrId
string
Example: qrId=AD1F2CD7212E48FA919AB52EF0AEFB33

Идентификатор QR-кода. Если значение не передано - выгружаются все операции по мерчанту

operationTypes
string
Enum: "Payment" "Refund"

Тип операции. Если значение не передано - выгружаются все типы операций

Responses

Response samples

Content type
application/json
{
  • "sbp": {
    },
  • "card": {
    }
}

Справочник ошибок

Если в процессе обработки любого запроса произойдет логическая ошибка, API вернет описание ошибки (message) и код сообщения (code).

Описание основных ошибок:

code message
ERROR.ACCOUNT_IS_NOT_REGISTERED Указан неверный счет. Проверьте его или удалите. Параметр является необязательным
ERROR.INVALID_REQUEST Не передан обязательный параметр
ERROR.QR_EXPIRATION_DATE_NOT_VALID Неверная дата истечения QR-кода
ERROR.MERCHANT_NOT_REGISTERED Партнер с ID * не зарегистрирован
ERROR.ORDER_NUMBER_ALREADY_REGISTERED QR-код с номером заказа *, партнера * и успешными платежами уже зарегистрирован
ERROR.INVALID_REQUEST Передана некорректная сумма платежа
ERROR.SBP_MERCHANT_ID_IS_MISSING SbpMerchantId партнера не указан
ERROR.DYNAMIC_QR_WITHOUT_AMOUNT Не передана сумма для динамического QR-кода
ERROR.INVALID_ORDER В номере заказа поддерживаются A-z09_-.
ERROR.NOT_FOUND QR-код не найден у данного партнера
ERROR.REFUND_INSUFFICIENT_FUNDS Сумма возврата больше суммы остатка по платежу
ERROR.INVALID_REQUEST Сумма возврата не может быть меньше 1 копейки
ERROR.REFUND_NOT_FOUND Возврат с refundId * не найден
ERROR.ERROR_WRONG_QR_STATUS Нельзя сменить статус QR-кода с * на *

История изменений

В таблице отражены важные изменения в методах API.

Дата Описание
18.10.2024 * Добавлен метод разделения платежа при создании qr или заказов на кассовую ссылку
10.07.2024 * Добавлены уведомления на операции возвратов
18.04.2024 * В методы сверок операций за период добавлен новый параметр - комиссия
09.11.2023 * Добавлен метод получения списка банков для возвратов
* Добавлен новый метод возврата, позволяющий совершить возврат на другие реквизиты
* Добавлен новый метод получения статуса возврата, который позволяет получить причину отклонения операции
19.06.2023 * Добавлена ссылка на SDK от НСПК , для реализации виджета выбора банка
18.05.2023 * В методы создания и привязки QR добавлен новый параметр qrDescription
29.03.2023 * Внесены ограничения по полям additionalInfo при создании заказов/qr и paymentDetails при возвратах
14.12.2022 * Добавлены методы для сверки операций по картам и СБП
02.11.2022 * Дополнен раздел "Подписки": добавлено описание методов работы
24.08.2022 * Дополнен раздел "Авторизация": добавлено описание подхода по созданию одного мерчанта на все торговые точки
* Метод регистрации QR вынесен в отдельный блок "Создание и отмена QR-кода (все типы QR)"
* Переименован раздел "Работа с QR-кодом" → "Статический и динамический QR-коды (QRStatic, QRDynamic)"
* Переименован раздел "Кассовая ссылка СБП" → "Кассовая ссылка СБП (QRVariable)"
* Добавлено описание статусов платежа в ответе на запрос статуса платежа по QR v1/qr/{qrId}/payment-info
* Удалены пометки required из ответов на некоторые запросы
* Корректировки по тексту
29.07.2022 * Изменены хосты:
* Боевой с e-commerce.raiffeisen.ru на pay.raif.ru
* Тестовый c test.ecom.raiffeisen.ru на pay-test.raif.ru
27.07.2022 * Добавлен параметр paymentDetails для возвратов по заказам по QRVariable
30.05.2022 * Добавлен параметр redirectUrl, который в случае успешной операции, позволяет передать ссылку для перенаправления клиента из приложения банка
30.12.2021 * Обновлены диаграммы последовательности UML в разделе "Общие схемы работы"
02.12.2021 * Добавлена диаграмма последовательности для работы с кассовой ссылкой СБП
* API для регистрации QR-кода версии v1 помечен как устаревший
* Добавлена новая версия v2 API для регистрации QR-кода
* Добавлен новый тип QR-кода QRVariable для кассовой ссылки СБП
* Добавлен новый API для создания заказов под QRVariable
* Добавлены пример JSON и cURL-запросов
* Дополнен справочник ошибок
* Внесены общие правки
09.09.2021 * Исправлена длина параметра paymentDetails при операциях возвратах
06.07.2021 * Реализовали сервис подписок
02.06.2021 * Добавили новый метод отмены QR-кода
* Появилась новая версия запроса на получения данных по QR-коду