Raiff logo
Documentation Powered by ReDoc

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-кода, который означает кассовую ссылку СБП и на уровне API и хранения данных отличает ее от статического и динамического QR-кодов.

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

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

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

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

Подписки

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

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

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

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

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

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

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

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

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

Сообщения о платежах можно получать в виде callback-уведомлений. В теле сообщения в объекте extra будет приходить ключ, переданный ранее при создании подписки или QR. Деактивировать подписку можно методом отмены подписки.

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

Для более быстрой интеграции вы можете воспользоваться нашими SDK:

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

Описание API

Bзаимодействие осуществляется по протоколу HTTP с использованием методов GET/POST/DELETE (в описании каждого запроса явно указан требуемый метод и адрес).

POST-запрос использует JSON-аргументы, GET и DELETE-запросы работают со строками запросов.

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

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

Авторизация

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

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

Посмотреть боевой sbpMerchantId и сгенерировать ключи можно в личном кабинете во вкладке "Прием платежей".

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

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

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

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

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

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

И подставить ее в url из параметра payload взамен https.

Для корректной работы выбора банка, рекомендуем использовать виджет от НСПК: IOS, Android, WEB - https://sbp.nspk.ru/business_online/#widget-business

Или вы можете воспользоваться нашими SDK: Android - https://github.com/Raiffeisen-DGTL/sbp-sdk-android IOS - https://github.com/Raiffeisen-DGTL/payform-sdk-ios

NFC и СБПэй

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

Необходимо на каждую кассу сгенерировать QR c типом QRVariable. Из ответа на запрос генерации QR, нужно получить ссылку из параметра payload, в ссылке в начало домена необходимо добавить "web." и полученную ссылку нужно зашить в NFC метку.

Пример:

В payload вы получили https://qr.nspk.ru/AS100004BAL7227F9BNP6KNE007J9B3K?type=01&bank=100000000007,

в NFC метку нужно будет зашить https://web.qr.nspk.ru/AS100004BAL7227F9BNP6KNE007J9B3K?type=01&bank=100000000007

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

Для полного цикла тестирования оплаты Райффайзенбанк предоставляет возможность использования демо-приложения для сканирования QR-кода от имени покупателя по адресу: https://pay.raif.ru/pay/rfuture/

Указанный адрес можно открыть в браузере любого устройства, где есть камера. Никакого дополнительного софта/плагинов устанавливать не нужно. Далее нажать на значок СБП (при необходимости разрешить браузеру доступ к камере) и поднести к ней изображение QR-кода. Если камера не открылась, проверьте, что в адресе указан протокол HTTPS.

Общие методы для QR-кодов и заказов (все типы QR)

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

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

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

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

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

Request Body schema: application/json
qrType
required
string

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

QRDynamic
QRDynamic
QRStatic
QRVariable
account
number <= 20

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

additionalInfo
string <= 140 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

amount
required
number

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

currency
string 3 characters
Value: "RUB"

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

order
required
string [ 1 .. 40 ] characters ^[A-z0-9-_.]

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

paymentDetails
string <= 185 characters

Назначение платежа в выписке получателя.

qrExpirationDate
string <YYYY-MM-DD ТHH24:MM:SS±HH:MM / +nM / +nm> non-empty

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

sbpMerchantId
required
string <= 12 characters

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

redirectUrl
string <uri>

Ссылка для автоматического возврата плательщика из приложения банка в приложение или на сайт магазина. Ссылка должна содержать https:// для web страниц или уникальную схему для мобильного приложения

qrDescription
string <= 32 characters

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

object

Используется для оплаты с последующей подпиской

object

Дополнительные поля для свободного заполнения по принципу key-value

Responses

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

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

qrStatus
string
Enum: "INACTIVE" "NEW" "IN_PROGRESS" "PAID" "EXPIRED" "CANCELLED"

Статус QR-кода
Статус NEW означает готовность к оплате. QR-код с типом QRStatic или QRDynamic создается в статусе NEW, QRVariable - в статусе INACTIVE

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

Опциональный параметр для указания срока действия QR-кода. После истечения срока действия QR-кода оплату по нему провести нельзя

payload
string

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

qrUrl
string

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

subscriptionId
string

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

Request samples

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

Response samples

Content type
application/json
Example
QRDynamic subscription
QRDynamic subscription
QRDynamic/QRStatic
QRVariable
{}

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

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

Тестовые QR можно оплатить только нашим тестовым приложением.

Request Body schema: application/json
qrType
required
string

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

QRDynamic
QRDynamic
QRStatic
account
number <= 20

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

additionalInfo
string <= 140 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

amount
required
number

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

currency
string 3 characters
Value: "RUB"

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

order
required
string [ 1 .. 40 ] characters ^[A-z0-9-_.]

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

paymentDetails
string <= 185 characters

Назначение платежа в выписке получателя.

qrExpirationDate
string <YYYY-MM-DD ТHH24:MM:SS±HH:MM / +nM / +nm> non-empty

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

sbpMerchantId
required
string <= 12 characters

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

redirectUrl
string <uri>

Ссылка для автоматического возврата плательщика из приложения банка в приложение или на сайт магазина. Ссылка должна содержать https:// для web страниц или уникальную схему для мобильного приложения

qrDescription
string <= 32 characters

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

object

Используется для оплаты с последующей подпиской

object

Дополнительные поля для свободного заполнения по принципу key-value

Responses

Response Schema: application/json
code
string <= 140 characters

Код сообщения

qrId
string <= 32 characters

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

payload
string

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

qrUrl
string

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

subscriptionId
string

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

Request samples

Content type
application/json
Example
QRDynamic
QRDynamic
QRDynamic (2)
QRDynamic subscription
QRStatic
{
  • "account": 40700000000000000000,
  • "additionalInfo": "Доп. информация",
  • "amount": 1110.11,
  • "currency": "RUB",
  • "order": "1-22-333",
  • "paymentDetails": "Назначение платежа",
  • "qrType": "QRDynamic",
  • "qrExpirationDate": "2023-07-22T09:14:38+03:00",
  • "sbpMerchantId": "MA0000000552"
}

Response samples

Content type
application/json
Example
QRDynamic subscription
QRDynamic subscription
QRDynamic/QRStatic
{}

Отмена QR

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

path Parameters
qrId
required
string

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

header Parameters
Authorization
required

Responses

Request samples 

curl --location --request DELETE 'https://pay-test.raif.ru/api/sbp/v2/qrs/ADAC306DDBF443CA94EBE3FA85CA4872' \
--header 'Authorization: Bearer eyJ0eXA***'

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

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

path Parameters
qrId
required
string

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

header Parameters
Authorization
required

Responses

Response Schema: application/json
qrId
string

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

qrStatus
string
Enum: "NEW" "IN_PROGRESS" "CANCELLED" "EXPIRED" "PAID"

Код состояния QR-кода

qrExpirationDate
string

Опциональный параметр для указания срока действия QR-кода. При заполнении не может быть меньше текущей даты и времени. После истечения срока действия QR-кода оплату по нему провести нельзя. Если Тип QR = QRDynamic и поле не заполнено, срок действия будет 3 суток. ISO 8601

payload
string

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

qrUrl
string

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

subscriptionId
string

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

Request samples 

curl --location --request GET 'https://pay-test.raif.ru/api/sbp/v2/qrs/ADAC306DDBF443CA94EBE3FA85CA4872' \
--header 'Authorization: Bearer eyJ0eXA***'

Response samples

Content type
application/json
{}

Получение списка банков

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

header Parameters
Authorization
required

Responses

Response Schema: application/json
Array
alias
string

Алиас Банка

name
string

Наименование Банка

Response samples

Content type
application/json
[
  • {
    • "alias": "RAIFFEISEN",
    • "name": "Райффайзенбанк"
    },
  • {
    • "alias": "TINKOFF",
    • "name": "Тинькофф"
    },
  • {
    • "alias": "VTB",
    • "name": "ВТБ"
    }
]

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

Метод позволяет выполнить возврат по платежу, как полный, так и частичный. Также в случае необходимости произвести возврат на другой номер и в другой банк, для этого необходимо заполнить bankAlias и phone, при такой операции будет произведена проверка ФИО плательщика оригинальнй операции с ФИО получателя возврата.

path Parameters
orderId
required
string <= 40 characters ^[A-z0-9-_.]

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

refundId
required
string <= 40 characters ^[A-z0-9-_.]

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

header Parameters
Authorization
required
Request Body schema: application/json
amount
required
integer

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

paymentDetails
string <= 140 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

object

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

Responses

Response Schema: application/json
amount
number

Сумма возврата в рублях

object

Request samples

Content type
application/json
Example
Обычный возврат
Обычный возврат
Возврат с изменением реквизитов
{
  • "amount": 10,
  • "paymentDetails": "Назначение платежа"
}

Response samples

Content type
application/json
{
  • "amount": 10,
  • "status": {
    • "value": "IN_PROGRESS",
    • "date": "2023-07-22T09:14:38+03:00"
    }
}

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

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

path Parameters
orderId
required
string <= 40 characters ^[A-z0-9-_.]

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

refundId
required
string <= 40 characters ^[A-z0-9-_.]

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

header Parameters
Authorization
required

Responses

Response Schema: application/json
amount
number

Сумма возврата в рублях

object

Response samples

Content type
application/json
Example
200(DECLINED)
200(DECLINED)
200(COMPLETED)
{
  • "amount": 10,
  • "status": {
    • "value": "DECLINED",
    • "date": "2023-07-22T09:14:38+03:00",
    • "declineReason": "TIMEOUT"
    }
}

Статический и динамический QR-коды (QRStatic, QRDynamic)

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

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

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

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

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

path Parameters
qrId
required
string

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

header Parameters
Authorization
required

Responses

Response Schema: application/json
code
string <= 140 characters

Код сообщения

qrId
string <= 32 characters

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

payload
string

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

qrUrl
string

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

subscriptionId
string

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

Request samples 

curl --location --request GET 'https://pay-test.raif.ru/api/sbp/v1/qr/AS6E5A7F9E3A4E648C536EC930AECDF6/info' \
--header 'Authorization: Bearer eyJ0eXA***'

Response samples

Content type
application/json
{}

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

Метод позволяет получить данные по платежу по QR. Метод не используется для QRVariable

path Parameters
qrId
required
string

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

header Parameters
Authorization
required

Responses

Response Schema: application/json
additionalInfo
string non-empty

Дополнительная информация, заполняемая по желанию партнёра при генерации QR-кода. Может быть доступна для пользователя в зависимости от банка. Не может быть пустым или содержать только пробелы. Может содержать:
• Символы латинского алфавита (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

paymentPurpose
string non-empty

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

amount
number

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

code
string non-empty

Код сообщения

createDate
string non-empty

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

currency
string non-empty
Value: "RUB"

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

merchantId
number
Deprecated

Уникальный идентификатор партнёра, выданный банком (не валидировать)

order
string non-empty

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

paymentStatus
string non-empty
Enum: "SUCCESS" "DECLINED" "NO_INFO" "IN_PROGRESS"

Статус платежа. Возможные значения:
• SUCCESS – платеж прошел успешно
• DECLINED – платеж отклонен
• NO_INFO – не найдена информация о платеже
• IN_PROGRESS – платеж в процессе обработки

qrId
string non-empty

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

sbpMerchantId
string non-empty

Уникальный идентификатор партнёра, выданный СБП

transactionDate
string non-empty

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

transactionId
integer

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

qrExpirationDate
string <YYYY-MM-DD ТHH24:MM:SS±HH:MM> non-empty

Время истечения срока жизни QR

object

Дополнительные поля, которые были заполнены ранее

Request samples 

curl --location --request GET 'https://pay-test.raif.ru/api/sbp/v1/qr/AS6E5A7F9E3A4E648C536EC930AECDF6/payment-info' \
--header 'Authorization: Bearer eyJ0eXA***'

Response samples

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

Оформление возврата по платежу Deprecated

Метод позволяет осуществлять полный и частичный возврат по QR. Метод не используется для QRVariable
Общий метод возврата с новым функционалом

header Parameters
Authorization
required
Request Body schema: application/json
amount
required
number

Сумма возврата в рублях

order
required
string <= 40 characters

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

paymentDetails
string <= 140 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

refundId
required
string <= 40 characters

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

transactionId
number

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

Responses

Response Schema: application/json
code
string

Код состояния HTTP-запроса

amount
number

Сумма возврата в рублях

refundStatus
string
Enum: "IN_PROGRESS" "COMPLETED" "DECLINED"

Код состояния запроса на возврат

Request samples

Content type
application/json
Example
QRDynamic
QRDynamic
QRStatic
{
  • "amount": 150,
  • "order": "test_order_007",
  • "paymentDetails": "Test",
  • "refundId": "test_refundId_007"
}

Response samples

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

Получение информации по возврату Deprecated

Получение информации по возврату. Метод не используется для QRVariable.
Также метод используется для проверки статуса возврата по подписке.
Общий метод получения информации по возврату с новым функционалом

path Parameters
refundId
required
string

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

header Parameters
Authorization
required

Responses

Response Schema: application/json
code
string

Код состояния HTTP-запроса

amount
number

Сумма возврата в рублях

refundStatus
string
Enum: "IN_PROGRESS" "COMPLETED" "DECLINED"

Код состояния запроса на возврат

Request samples 

curl --location --request GET 'https://pay-test.raif.ru/api/sbp/v1/refund/111112222200046' \
--header 'Authorization: Bearer eyJ0eXA***'

Response samples

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

Кассовая ссылка СБП (QRVariable)

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

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

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

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

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

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

header Parameters
Authorization
required
Request Body schema: application/json
id
string [ 1 .. 40 ] characters ^[A-z0-9-_.]

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

amount
required
number <float>

Сумма заказа

comment
string <= 140 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

object

Дополнительные поля для свободного заполнения по принципу key-value

expirationDate
string <YYYY-MM-DD ТHH24:MM:SS±HH:MM / +nM / +nm>

Дата истечения срока заказа
Может содержать точную дату и время или количество минут (целых). Передача срока в минутах удобна для торговых точек, которые не привязываются к точному времени или часовому поясу
Параметр не может быть меньше текущей даты и времени
Если параметр не передан, то срок заказа по умолчанию 15 минут. Если при этом также передан объект qr, то QR-код также будет активен для оплаты 15 минут. При переданном QR, минимальный срок действия - 1 минута, максимальный - 20 минут

object

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

Responses

Response Schema: application/json
id
string [ 1 .. 40 ] characters ^[A-z0-9-_.]

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

amount
number <float>

Сумма заказа

comment
string

Комментарий к заказу

object

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

object
expirationDate
string <date-time>

Дата истечения срока заказа

object

Блок с данными QR-кода

Request samples

Content type
application/json
Example
Создание заказа
Создание заказа
Создание заказа (2)
{
  • "id": "c5b3fd07-c66b-4f11-a8a2-1cc5d319f9e3",
  • "amount": 1000.1,
  • "comment": "Шоколадный торт",
  • "extra": {
    • "extraParam": "Example extra param"
    },
  • "expirationDate": "2023-01-24T11:14:38+03:00",
  • "qr": {
    • "id": "AD100004BAL7227F9BNP6KNE007J9B3K",
    • "additionalInfo": "Доп. информация",
    • "paymentDetails": "Назначение платежа"
    }
}

Response samples

Content type
application/json
{
  • "id": "c5b3fd07-c66b-4f11-a8a2-1cc5d319f9e3",
  • "amount": 1000.1,
  • "comment": "Шоколадный торт",
  • "extra": {
    • "extraParam": "Example extra param"
    },
  • "status": {
    • "value": "NEW",
    • "date": "2021-12-24T11:15:22.000Z"
    },
  • "expirationDate": "2022-01-24T11:15:22.000Z",
  • "qr": {
    • "id": "AD100004BAL7227F9BNP6KNE007J9B3K",
    • "additionalInfo": "Доп. информация",
    • "paymentDetails": "Назначение платежа"
    }
}

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

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

path Parameters
orderId
required
string <= 40 characters ^[A-z0-9-_.]

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

header Parameters
Authorization
required

Responses

Response Schema: application/json
id
string [ 1 .. 40 ] characters ^[A-z0-9-_.]

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

amount
number <float>

Сумма заказа

comment
string

Комментарий к заказу

object

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

object
expirationDate
string <date-time>

Дата истечения срока заказа

object

Блок с данными QR-кода

Request samples 

curl --location --request GET 'https://pay-test.raif.ru/api/payment/v1/orders/c5b3fd07-c66b-4f11-a8a2-1cc5d319f9e3' \
--header 'Authorization: Bearer eyJ0eXA***'

Response samples

Content type
application/json
{
  • "id": "c5b3fd07-c66b-4f11-a8a2-1cc5d319f9e3",
  • "amount": 1000.1,
  • "comment": "Шоколадный торт",
  • "extra": {
    • "extraParam": "Example extra param"
    },
  • "status": {
    • "value": "NEW",
    • "date": "2021-12-24T11:15:22.000Z"
    },
  • "expirationDate": "2022-01-24T11:15:22.000Z",
  • "qr": {
    • "id": "AD100004BAL7227F9BNP6KNE007J9B3K",
    • "additionalInfo": "Доп. информация",
    • "paymentDetails": "Назначение платежа"
    }
}

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

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

path Parameters
orderId
required
string <= 40 characters ^[A-z0-9-_.]

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

header Parameters
Authorization
required

Responses

Request samples 

curl --location --request DELETE 'https://pay-test.raif.ru/api/payment/v1/orders/c5b3fd07-c66b-4f11-a8a2-1cc5d319f9e3' \
--header 'Authorization: Bearer eyJ0eXA***'

Response samples

Content type
application/json
{
  • "code": "ORDER_HAS_FINAL_STATUS",
  • "message": "Заказ с идентификатором test123 имеет статус PAID"
}

Оформление возврата по заказу Deprecated

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

path Parameters
orderId
required
string <= 40 characters ^[A-z0-9-_.]

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

refundId
required
string <= 40 characters ^[A-z0-9-_.]

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

header Parameters
Authorization
required
Request Body schema: application/json
amount
required
number

Сумма возврата в рублях

paymentDetails
string <= 140 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

Responses

Response Schema: application/json
code
string
Enum: "SUCCESS" "ERROR"

Код состояния http запроса. Возвращается при version=1

amount
number

Сумма возврата в рублях

refundStatus
string
Enum: "IN_PROGRESS" "COMPLETED" "DECLINED"

Код состояния запроса на возврат. Возвращается при version=1

Request samples

Content type
application/json
{
  • "amount": 150
}

Response samples

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

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

Метод позволяет получить статус по возврату
Общий метод получения информации по возврату с новым функционалом

path Parameters
orderId
required
string <= 40 characters ^[A-z0-9-_.]

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

refundId
required
string <= 40 characters ^[A-z0-9-_.]

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

header Parameters
Authorization
required

Responses

Response Schema: application/json
code
string
Enum: "SUCCESS" "ERROR"

Код состояния http запроса. Возвращается при version=1

amount
number

Сумма возврата в рублях

refundStatus
string
Enum: "IN_PROGRESS" "COMPLETED" "DECLINED"

Код состояния запроса на возврат. Возвращается при version=1

Request samples 

curl --location --request GET 'https://pay-test.raif.ru/api/payments/v1/orders/c5b3fd07-c66b-4f11-a8a2-1cc5d319f9e3/refunds/44e128a5-ac7a-4c9a-be4c-224b6bf81b21' \
--header 'Authorization: Bearer eyJ0eXA***'

Response samples

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

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

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

path Parameters
qrId
required
string

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

header Parameters
Authorization
required
Request Body schema:
application/json
application/json
application/xml
multipart/form-data
account
string

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

redirectUrl
string

Ссылка для автоматического возврата плательщика из приложения банка в приложение или на сайт магазина. Ссылка должна содержать https:// для web страниц или уникальную схему для мобильного приложения

qrDescription
string <= 32 characters

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

Responses

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

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

qrStatus
string
Enum: "INACTIVE" "NEW" "IN_PROGRESS" "PAID" "EXPIRED" "CANCELLED"

Статус QR-кода
Статус NEW означает готовность к оплате. QR-код с типом QRStatic или QRDynamic создается в статусе NEW, QRVariable - в статусе INACTIVE

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

Опциональный параметр для указания срока действия QR-кода. После истечения срока действия QR-кода оплату по нему провести нельзя

payload
string

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

qrUrl
string

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

subscriptionId
string

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

Request samples

Content type
application/json
application/json
application/xml
multipart/form-data
{
  • "account": "40700000000000000000",
  • "redirectUrl": "https://bfkh.ru/",
  • "qrDescription": "QR на главной кассе"
}

Response samples

Content type
application/json
{}

Подписки

Для включения функционала подписок необходима дополнительная настройка со стороны банка. Выполняется при обращении в тех. поддержку.

Посмотреть клиентский путь можно с помощью нашей демо страницы - https://pay.raif.ru/pay/configurator/#/subscription

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

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

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

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

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

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

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

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

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

Request Body schema: application/json
id
string <= 100 characters

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

subscriptionPurpose
required
string <= 185 characters

Описание подписки которое увидит клиент в приложении банка.

sbpMerchantId
required
string

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

redirectUrl
string <uri>

Ссылка для автоматического возврата плательщика из приложения банка в приложение или на сайт магазина. Ссылка должна содержать https:// для web страниц или уникальную схему для мобильного приложения.

object (autoCharge)

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

object

Дополнительные поля для свободного заполнения по принципу key-value
Если передан объект autoCharge, то в extra необходимо передать ключ, который вернется в теле callback-уведомления. Это позволит соотнести подписку и автоматические платежи по ней

Responses

Response Schema: application/json
id
string

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

createDate
string

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

status
string
Enum: "INACTIVE" "SUBSCRIBED" "UNSUBSCRIBED" "CANCELLED"

Статус подписки

object

Данные по QR-подписки

Request samples

Content type
application/json
Example
QR для подписки со списанием по запросу
QR для подписки со списанием по запросу
QR для подписки с автоматическим списанием
{
  • "id": "120059",
  • "subscriptionPurpose": "Подписка на услуги",
  • "redirectUrl": "https://bfkh.ru/",
  • "sbpMerchantId": "MA0000000552"
}

Response samples

Content type
application/json
{}

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

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

path Parameters
subscriptionId
required
string

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

header Parameters
Authorization
required

Responses

Response Schema: application/json
id
string

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

bank
string

Идентификатор банка в котором осуществленна подписка.

createDate
string

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

status
string
Enum: "INACTIVE" "SUBSCRIBED" "UNSUBSCRIBED" "CANCELLED"

Статус подписки

object

Данные по QR-подписки

Response samples

Content type
application/json
{}

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

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

path Parameters
subscriptionId
required
string

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

header Parameters
Authorization
required

Responses

Request samples 

curl --location --request DELETE 'https://pay-test.raif.ru/api/sbp/v1/subscriptions/120059' \
--header 'Authorization: Bearer eyJ0eXA***'

Response samples

Content type
application/json
{
  • "code": "ERROR.SUBSCRIPTION_STATUS_CONFLICT",
  • "message": "Подписка c id 120059 находится в статусе CANCELLED, действие невозможно"
}

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

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

path Parameters
subscriptionId
required
string

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

header Parameters
Authorization
required
Request Body schema: application/json
account
number

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

additionalInfo
required
string <= 140 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

amount
required
number

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

currency
required
string
Value: "RUB"

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

order
string <= 40 characters

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

paymentDetails
string <= 185 characters

Назначение платежа. Необязательно для заполнения.

Responses

Response Schema: application/json
additionalInfo
string

Дополнительная информация, заполняемая по желанию партнёра при генерации QR-кода. Может быть доступна для пользователя в зависимости от банка Не может быть пустым или содержать только пробелы. Может содержать:
• Символы латинского алфавита (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

paymentDetails
string

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

amount
number

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

currency
string
Value: "RUB"

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

order
string

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

paymentStatus
string
Enum: "SUCCESS" "DECLINED" "IN_PROGRESS"

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

qrId
string

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

sbpMerchantId
string

Уникальный идентификатор партнёра, выданный СБП

Request samples

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

Response samples

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

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

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

path Parameters
subscriptionId
required
string

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

order
required
string

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

header Parameters
Authorization
required

Responses

Response Schema: application/json
additionalInfo
string

Дополнительная информация, заполняемая по желанию партнёра при генерации QR-кода. Может быть доступна для пользователя в зависимости от банка Не может быть пустым или содержать только пробелы. Может содержать:
• Символы латинского алфавита (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

paymentDetails
string

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

amount
number

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

currency
string
Value: "RUB"

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

order
string

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

paymentStatus
string
Enum: "SUCCESS" "DECLINED" "IN_PROGRESS"

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

qrId
string

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

sbpMerchantId
string

Уникальный идентификатор партнёра, выданный СБП

Response samples

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

Уведомления

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

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

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

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

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

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

Для проверки подлинности уведомления по QRStatic и QRDynamic к данным добавляется подпись в заголовке X-Api-Signature-SHA256, полученная на основе общего секретного ключа и контрольной строки (amount|sbpMerchantId|order|paymentStatus|transactionDate) с помощью HMAC-SHA-256.

Для проверки подлинности уведомления по QRVariable к данным добавляется подпись в заголовке X-Api-Signature-SHA256, полученная на основе общего секретного ключа и контрольной строки (amount|publicId|order|transaction.status.value|transaction.status.date) с помощью HMAC-SHA-256.

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

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

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 <= 140 characters

Дополнительная информация, заполняемая по желанию ТСП при генерации QR-кода. Может быть доступна для пользователя в зависимости от банка. Не может быть пустым или содержать только пробелы. Может содержать:
• Символы латинского алфавита (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

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": "Some info",
  • "order": "testOrder",
  • "createDate": "2020-01-15T13:00:40+03:00",
  • "extra": {
    • "extraParam": "Example extra param"
    }
}

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

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

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

object

Request samples

Content type
application/json
{
  • "event": "payment",
  • "transaction": {
    • "id": 120059,
    • "orderId": "testOrder",
    • "status": {
      • "value": "SUCCESS",
      • "date": "2019-07-11T17:45:13+03:00"
      },
    • "paymentMethod": "sbp",
    • "paymentParams": {
      • "qrId": "AD100051KNSNR64I98CRUJUASC9M72QT"
      },
    • "amount": 12500.5,
    • "comment": "Покупка шоколадного торта",
    • "extra": {
      • "extraParam": "Example extra param"
      }
    }
}

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

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

header Parameters
Authorization
required
Request Body schema: application/json
callbackUrl
required
string non-empty

Responses

Response Schema: application/json
callbackUrl
string

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

Реестр

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

Реестры по платежам отправляются на ежедневной основе.

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

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

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

Пример реестра

Выписка

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

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

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

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

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

Отчёт по транзакциям за указанный период (не более трёх дней)

query Parameters
from
required
string <URL encoded> YYYY-MM-DD ТHH24:MM:SS±HH:MM

Дата и время начала выборки

to
required
string <URL encoded> YYYY-MM-DD ТHH24:MM:SS±HH:MM

Дата и время окончания выборки

operationTypes
string
Enum: "Payment" "Refund"

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

qrId
string

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

header Parameters
Authorization

Responses

Response Schema: application/json
object

Операции СБП

object

Операции по интернет-эквайрингу

Request samples 

curl --location --request GET 'https://pay-test.raif.ru/api/report/v1/transactions/summary?from=2023-01-10T00%3A00%3A00%2B03%3A00&to=2023-01-10T23%3A59%3A59%2B03%3A00&qrId=AS37213C7A834E7FBBB76B6D06DFB4B9' \
--header 'Authorization: Bearer eyJ0eXAi***'

Response samples

Content type
application/json
{
  • "sbp": {
    • "payments": {
      • "sum": 21,
      • "count": 2,
      • "fee": 0.08
      },
    • "refunds": {
      • "sum": 10,
      • "count": 1,
      • "fee": 0
      },
    • "total": {
      • "sum": 11,
      • "count": 3,
      • "fee": 0.08
      }
    },
  • "card": {
    • "payments": {
      • "sum": 23,
      • "count": 2,
      • "fee": 0.62
      },
    • "refunds": {
      • "sum": 11,
      • "count": 1,
      • "fee": 0
      },
    • "total": {
      • "sum": 12,
      • "count": 3,
      • "fee": 0.62
      }
    }
}

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

Получение детализированного отчёта по транзакциям за указанный период (не более трёх дней)

query Parameters
from
required
string <URL encoded> YYYY-MM-DD ТHH24:MM:SS±HH:MM

Дата и время начала выборки

to
required
string <URL encoded> YYYY-MM-DD ТHH24:MM:SS±HH:MM

Дата и время окончания выборки

operationTypes
string
Enum: "Payment" "Refund"

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

qrId
string

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

header Parameters
Authorization

Responses

Response Schema: application/json
object

Операции СБП

object

Операции по интернет-эквайрингу

Request samples 

curl --location --request GET 'https://pay-test.raif.ru/api/report/v1/transactions?from=2023-01-10T00%3A00%3A00%2B03%3A00&to=2023-01-10T23%3A59%3A59%2B03%3A00&qrId=AS37213C7A834E7FBBB76B6D06DFB4B9' \
--header 'Authorization: Bearer eyJ0eXAi***'

Response samples

Content type
application/json
{
  • "sbp": {
    • "payment": [
      • {
        • "orderId": "a3294_3FFERSer_RE",
        • "amount": 77,
        • "transactionDate": "2022-12-08T13:21:04.631543+03:00",
        • "paymentSystem": "Instant Payment QR",
        • "paymentDetails": "Благотворительное пожертвование",
        • "transactionId": 178657,
        • "clientId": "007910******4567",
        • "qrId": "AS1A007L7B8IPA1F8CBQ8RK2D27FHST9",
        • "sbpTransactionId": "A23091339574920E000009529E6B66DF",
        • "orderComment": "Комментарий",
        • "fee": 0.31
        }
      ],
    • "refund": [
      • {
        • "orderId": "a3294_3FFERSer_RE",
        • "amount": 17,
        • "transactionDate": "2022-12-09T13:17:04.631543+03:00",
        • "paymentSystem": "Instant Payment QR",
        • "paymentDetails": "Возврат денежных средств",
        • "transactionId": 178658,
        • "clientId": "007910******4567",
        • "qrId": "AS1A007L7B8IPA1F8CBQ8RK2D27FHST9",
        • "sbpTransactionId": "B229701403532102000016268EEA632B",
        • "refundId": "refundOrder1",
        • "fee": 0
        }
      ]
    },
  • "card": {
    • "payment": [
      • {
        • "orderId": "xU5q5XG8m3oaDGKOTWg01671000652444",
        • "amount": 14,
        • "transactionDate": "2022-12-14T09:51:02.339+03:00",
        • "paymentSystem": "VISA",
        • "paymentDetails": "Назначение платежа",
        • "transactionId": 5252420,
        • "clientId": "200043****823",
        • "authCode": "259AA",
        • "rrn": "935014591810",
        • "orderComment": "Благотворительное пожертвование",
        • "fee": 0.38
        }
      ],
    • "refund": [
      • {
        • "orderId": "xU5q5XG8m3oaDGKOTWg01671000652444",
        • "amount": 13,
        • "transactionDate": "2022-12-14T10:01:24.84+03:00",
        • "paymentSystem": "VISA",
        • "paymentDetails": "Назначение платежа",
        • "transactionId": 5252440,
        • "clientId": "200043****823",
        • "authCode": "259AA",
        • "rrn": "935014591810",
        • "refundId": "refundId1",
        • "fee": 0
        }
      ]
    }
}

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

Если в процессе обработки любого запроса произойдет логическая ошибка, 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-кода с * на *

06.07.2021

09.09.2021

  • Исправлена длина параметра paymentDetails при операциях возвратах

02.12.2021

  • Добавлена диаграмма последовательности для работы с кассовой ссылкой СБП
  • API для регистрации QR-кода версии v1 помечен как устаревший
  • Добавлена новая версия v2 API для регистрации QR-кода
  • Добавлен новый тип QR-кода QRVariable для кассовой ссылки СБП
  • Добавлен новый API для создания заказов под QRVariable
  • Добавлены пример JSON и cURL-запросов
  • Дополнен справочник ошибок
  • Внесены общие правки

30.12.2021

  • Обновлены диаграммы последовательности UML в разделе "Общие схемы работы"

30.05.2022

  • Добавлен параметр redirectUrl, который позволяет передать ссылку для перенаправления клиента из приложения банка, в случае успешной операции.

27.07.2022

  • Добавлен параметр paymentDetails для возвратов по заказам по QRVariable

29.07.2022

  • Изменены хосты:
  • Боевой с e-commerce.raiffeisen.ru на pay.raif.ru
  • Тестовый c test.ecom.raiffeisen.ru на pay-test.raif.ru

24.08.2022

  • Дополнен раздел "Авторизация": добавлено описание подхода по созданию одного мерчанта на все торговые точки
  • Метод регистрации QR вынесен в отдельный блок "Создание и отмена QR-кода (все типы QR)"
  • Переименован раздел "Работа с QR-кодом" → "Статический и динамический QR-коды (QRStatic, QRDynamic)"
  • Переименован раздел "Кассовая ссылка СБП" → "Кассовая ссылка СБП (QRVariable)"
  • Добавлено описание статусов платежа в ответе на запрос статуса платежа по QR v1/qr/{qrId}/payment-info
  • Удалены пометки required из ответов на некоторые запросы
  • Корректировки по тексту

02.11.2022

  • Дополнен раздел "Подписки": добавлено описание методов работы

14.12.2022

  • Добавлены методы для сверки операций по картам и СБП

29.03.2023

  • Внесены ограничения по полям additionalInfo при создании заказов/qr и paymentDetails при возвратах

18.05.2023

  • В методы создания и привязки QR добавлен новый параметр qrDescription

19.06.2023

  • Добавлена ссылка на SDK от НСПК , для реализации виджета выбора банка

09.11.2023

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

18.04.2024

  • В методы сверок операций за период добавлен новый параметр комиссия