Raiff logo
API docs by Redocly

Raiffeisenbank e-commerce API (1.0)

Download OpenAPI specification:Download

Support e-mail: ecom@raiffeisen.ru

Подключение к эквайрингу

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

По вопросам работы с API можно обращаться в службу поддержки Raiffeisenbank:

Подготовительные мероприятия

Чтобы принимать платежи:

  • Заполните заявку на подключение эквайринга
  • Выберите способ интеграции и реализуйте его
  • Проведите тестовые платежи

Способы интеграции платежной страницы

Для интеграции платежной страницы используйте:

  • Готовую библиотеку, позволяющую открыть popup для ввода данных платежа и передать сложную структуру данных
  • Редирект клиента на платежную страницу Райффайзенбанка

Поддержка 54-ФЗ

По закону от 22.05.2003 № 54–ФЗ "О применении контрольно-кассовой техники при осуществлении расчетов в Российской Федерации" при оплате товаров, работ или услуг необходимо формировать фискальный чек и отправлять его в налоговую с помощью кассы.

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

Описание API

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

При отправке запросов на открытие платежной формы и создание заказа с открытием платежной формы, API возвращает ответ в формате HTML документа, ответы на остальные запросы возвращаются в формате JSON.

Авторизация

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

  • publicId - Идентификатор, который используется для открытия платежной формы и является публичным.
  • secretKey - Секретный ключ, который используется для межсервисного взаимодействия. Является приватным, необходимо хранить в защищенном месте и не передавать третьим лицам.
Контур Адрес обращения
Production https://pay.raif.ru
Test https://pay-test.raif.ru

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

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

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

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

Схемы работы

Платежная форма банка

Демонстрация: Платежная форма

Способы работы с платежной формой

Способ 1. Метод "Создание заказа с открытием формы"

Метод [Создание заказа с открытием формы] возвращает HTML-форму для открытия платежной страницы. Мерчант может открыть форму в iframe, новом окне или использовать редирект.

Способ 2. Создание заказа с получением платежной ссылки

Используйте метод [Создание заказа с получением платежной ссылки] для формирования заказа и получения уникальной платежной ссылки вида https://pay.raif.ru/pay?payformId=${payformId}.

Мерчант может:

  • Перенаправить клиента на платежную страницу через браузер
  • Отправить ссылку клиенту в email, SMS или мессенджере
  • Открыть ссылку с помощью JS SDK на своей странице

Преимущества:

  • Уникальная ссылка для каждого заказа
  • Возможность отправки ссылки в уведомлениях
  • Клиент может открыть ссылку в любой момент

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

Способ 3. Открытие формы через JS SDK

Для открытия платежной формы в popup-окне без редиректа с сайта мерчанта используйте JS SDK. Подробнее в разделе [SDK].

Подписки и привязки

Банк поддерживает сценарий подписки — обобщающее понятие, которое включает:

  • Классическую подписку — автоматические рекуррентные списания по расписанию
  • Привязку счета СБП или карты — возможность проводить списания по инициативе мерчанта

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

Способы оформления подписки

Способ 1. Через создание заказа с платежной формой

Используйте метод [Создание заказа с получением платежной ссылки], передав объект subscription в теле запроса.

В ответе вы получите:

  • payformUrl — ссылка на платежную форму
  • subscriptionId — идентификатор подписки (после успешного оформления)
  • Данные по заказу

На платежной форме плательщик сможет выбрать: оплатить с оформлением подписки или просто оплатить.

Способ 2. Через форму подписки

Используйте метод [Создание подписки на форме] для получения ссылки на форму привязки.

При привязке карты производится проверка карты.

  • С карты списывается 11 рублей
  • Сумма сразу возвращается плательщику
  • Данная схема применяется только для привязки карты

Уведомления после оформления

После успешного оформления подписки/привязки любым из способов:

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

Для списаний по успешно оформленной подписке используйте [Метод создания платежа].

Демо-страница подписок — здесь можно протестировать сценарий подписки и увидеть доступные методы API.

Статусные модели

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

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

Статусная модель заказа:

Статусная модель заказа

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

Статусная модель подписки:

Статусная модель подписки

Статусная модель платежа:

Статусная модель платежа

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

Эквайринг

Платежная форма Банка:

PAN карты Срок действия карты CVV OTP код Сценарий платежа
4000001000000018 12/35 880 1234 Успешная оплата
4000001000000018 12/35 880 1111 Неуспешная оплата

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

СБП

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

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

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

SDK

Использование JS SDK позволяет открывать форму с frontend части в pop-up окне, либо осуществлять редирект пользователя на страницу Райффайзенбанка, что обеспечивает бесшовный сценарий оплаты для клиента.

Дополнительно можно кастомизировать интерфейс платежной формы и передавать дополнительные параметры для последующей оплаты. Настроить визуальную часть формы (название компании, логотип, цвет кнопок) можно в Конфигураторе платежной формы.

Также конфигуратор платежной формы позволяет получить код для встраивания его в JS-библиотеку.

Доступные SDK:

JS SDK позволяет открывать платежную форму с frontend части вашего приложения. При использовании остальных SDK для работы с платежной формой необходимо либо самостоятельно использовать методы, описанные в разделе [Платежная форма], либо использовать дополнительно JS SDK.

Также плагины для различных CMS можно найти в GitHub.

Вопросы по поддержке решений можно направлять в техническую поддержку: ecom@raiffeisen.ru

Платежная форма банка

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

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

Открытие платежной формы

При редиректе клиента на полученный URL откроется форма для оплаты. Для проверки суммы, поступившей от клиента, рекомендуется настроить Уведомление о платеже и сверять суммы созданного заказа и оплаты. Кастомизация интерфейса платежной формы или передача дополнительных полей в данном варианте интеграции недоступна.

query Parameters
publicId
required
string

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

orderId
string <= 40 characters ^[A-z0-9-_.]+$
Example: orderId=order-test

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

amount
required
number >= 0.01

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

comment
string <URL encoded> <= 140 characters
Example: comment=%D0%9A%D0%BE%D0%BC%D0%BC%D0%B5%D0%BD%D1%82%D0%B0%D1%80%D0%B8%D0%B9

Комментарий. Не может быть пустым или содержать только пробелы. Может содержать:
• Символы латинского алфавита (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

successUrl
string <uri>

URL-адрес ресурса, куда будет перенаправлен плательщик в случае успешной оплаты

failUrl
string <uri>

URL-адрес ресурса, куда будет перенаправлен плательщик в случае неуспешной оплаты

paymentMethod
string
Enum: "ONLY_SBP" "ONLY_ACQUIRING"

Метод оплаты

locale
string
Default: "ru"
Enum: "ru" "en"

Язык, используемый в интерфейсе платежной формы

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

Срок жизни заказа. YYYY-MM-DDТHH24:MM:SS±HH:MM

successSbpUrl
string <uri>

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

paymentDetails
string <URL encoded> <= 140 characters

Назначение платежа в выписке, используется при оплате по СБП

Responses

Создание заказа с открытием формы

Метод позволяет создать заказ с открытием формы

Request Body schema: application/json
One of
publicId
required
string

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

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

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

amount
required
number >= 0.01

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

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

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

successUrl
string <uri>

Адрес, на который будет перенаправлен плательщик с платежной формы в случае успешной оплаты

  • Допускается использование схемы http или https, за которой следует :// и последовательность символов без пробелов.
failUrl
string <uri>

Адрес, на который будет перенаправлен плательщик с платежной формы в случае неуспешной оплаты

  • Допускается использование схемы http или https, за которой следует :// и последовательность символов без пробелов.
object (Extra)

Дополнительные поля в формате key-value. Отображаются в реестрах.

paymentMethod
string (PayformPaymentMethod)
Enum: "ONLY_SBP" "ONLY_ACQUIRING"

Способ оплаты

  • ONLY_SBP - Оплата по СБП
  • ONLY_ACQUIRING - Оплата по карте
locale
string = 2 characters
Default: "ru"
Enum: "ru" "en"

Язык, используемый в интерфейсе платежной формы

expirationDate
string <date-time>

Срок жизни заказа

successSbpUrl
string^[A-Za-z][A-Za-z0-9]*://\S+$

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

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

Назначение платежа в выписке, используется при оплате по СБП

Responses

Request samples

Content type
application/json
Example
{
  • "publicId": "000001680200002-80200002",
  • "orderId": "order-test",
  • "amount": 1200.37,
  • "comment": "Тестовый комментарий",
  • "successUrl": "http://example.com",
  • "failUrl": "http://example.com",
  • "extra": {
    },
  • "paymentMethod": "ONLY_SBP",
  • "locale": "ru",
  • "expirationDate": "2025-01-10T20:10:00+03:00",
  • "successSbpUrl": "https://bfkh.ru/",
  • "paymentDetails": "Назначение платежа"
}

Response samples

Content type
application/json
{
  • "timestamp": "2024-12-15T06:36:32+03:00",
  • "status": 415,
  • "error": "Unsupported Media Type",
  • "path": "string"
}

Оформление подписки на форме

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

path Parameters
publicId
required
string

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

Request Body schema: application/json
required
methods
Array of strings (PaymentMethod)
Items Enum: "ACQUIRING" "SBP"

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

locale
string
Default: "RU"
Enum: "RU" "EN"

Язык, используемый в интерфейсе формы

object

Адреса для перенаправления плательщика на ресурсы мерчанта

required
object (Subscription)

Данные для оформления подписки и будущих рекурентных платежей. Результат подписки зависит от плательщика. При успешной подписке будет отправлено [Уведомление о подписке на адрес мерчанта].

Responses

Request samples

Content type
application/json
{
  • "methods": [
    ],
  • "locale": "RU",
  • "returnUrls": {},
  • "subscription": {
    }
}

Response samples

Content type
application/json
{
  • "payformUrl": "http://example.com",
  • "subscription": {
    }
}

Создание заказа с получением платежной ссылки

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

Authorizations:
secretKey
path Parameters
publicId
required
string

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

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

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

amount
required
number > 0

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

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

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

object (Extra)

Дополнительные поля в формате key-value. Отображаются в реестрах.

expirationDate
string <date-time>

Срок жизни заказа

paymentDetails
string <= 140 characters

Назначение платежа в выписке, используется при оплате по СБП

paymentMethods
Array of strings (PaymentMethod)
Items Enum: "ACQUIRING" "SBP"

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

locale
string
Default: "RU"
Enum: "RU" "EN"

Язык, используемый в интерфейсе платежной формы

object

Адреса для перенаправления плательщика на ресурсы мерчанта

object (Receipt)

Данные чека. Объект должен быть передан, если подключена фискализация чеков. При отсутствии объекта receipt чек не будет создан. Если объект receipt был передан, но заполнен некорректно, сервис вернет ошибку.

object (PaymentSlip)

В РАЗРАБОТКЕ
Данные квитанции. Следует заполнять, если подключен функционал квитанций и необходимо кастомизировать данные, которые отобразятся в квитанции

object (Subscription)

Данные для оформления подписки и будущих рекурентных платежей. Результат подписки зависит от плательщика. При успешной подписке будет отправлено [Уведомление о подписке на адрес мерчанта].

Array of objects (Split)

В РАЗРАБОТКЕ
Набор параметров для сплитования платежа.
Для сплитования сумма всех объектов внутри сплита должна быть равна сумме заказа.

Responses

Request samples

Content type
application/json
Example
{
  • "id": "order-test",
  • "amount": 1200,
  • "comment": "Тестовый комментарий",
  • "paymentDetails": "Назначение платежа",
  • "paymentMethods": [
    ],
  • "returnUrls": {},
  • "receipt": {
    }
}

Response samples

Content type
application/json
Example
{
  • "id": "order-test",
  • "amount": 1200,
  • "comment": "Тестовый комментарий",
  • "extra": {
    },
  • "expirationDate": "2025-01-10T20:10:00+03:00",
  • "paymentDetails": "string",
  • "status": {
    },
  • "payformUrl": "https://pay.raif.ru/pay?payformId=1238ana84",
  • "receipt": {
    }
}

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

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

API для данного сценария может быть расширяемым.

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

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

Привязку можно создать:

Authorizations:
secretKey
path Parameters
publicId
required
string

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

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

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

amount
required
number > 0

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

object (Order)

Заказ

object (Extra)

Дополнительные поля в формате key-value. Отображаются в реестрах.

flow
required
string (PaymentFlow)
paymentDetails
string <= 140 characters

Назначение платежа. Используется для оплаты по подписке СБП.

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

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

recurringType
required
string (SubscriptionRecurringType)
Enum: "SCHEDULED" "UNSCHEDULED"

Тип повторяющегося платежа

  • SCHEDULED - плата за подписку на услугу / сервис, инициированная ТСП на регулярной основе
  • UNSCHEDULED - покупка без графика
object (Receipt)

Данные чека. Объект должен быть передан, если подключена фискализация чеков. При отсутствии объекта receipt чек не будет создан. Если объект receipt был передан, но заполнен некорректно, сервис вернет ошибку.

Responses

Request samples

Content type
application/json
{
  • "id": "payment-test",
  • "amount": 540,
  • "order": {
    },
  • "extra": {
    },
  • "flow": "SUBSCRIPTION",
  • "recurringType": "UNSCHEDULED",
  • "paymentDetails": "Оплата молока на Фрунзе 1",
  • "subscriptionId": "subscription-test"
}

Response samples

Content type
application/json
{
  • "id": "payment-test",
  • "amount": 540,
  • "order": {
    },
  • "extra": {
    },
  • "flow": "SUBSCRIPTION",
  • "status": {
    },
  • "stage": "CREATED_SUBSCRIPTION_PAYMENT",
  • "paymentDetails": "Оплата молока на Фрунзе 1",
  • "subscriptionId": "subscription-test",
  • "recurringType": "UNSCHEDULLED",
  • "parameters": {
    }
}

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

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

Authorizations:
secretKey
path Parameters
publicId
required
string

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

id
required
string

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

Responses

Response samples

Content type
application/json
{
  • "id": "payment-test",
  • "amount": 540,
  • "order": {
    },
  • "extra": {
    },
  • "flow": "SUBSCRIPTION",
  • "status": {
    },
  • "stage": "CREATED_SUBSCRIPTION_PAYMENT",
  • "paymentDetails": "Оплата молока на Фрунзе 1",
  • "subscriptionId": "subscription-test",
  • "recurringType": "UNSCHEDULLED",
  • "parameters": {
    }
}

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

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

Authorizations:
secretKey
path Parameters
publicId
required
string

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

id
required
string

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

Responses

Response samples

Content type
application/json
Example
{
  • "id": "subscription-test",
  • "status": {
    },
  • "purpose": "Подписка на интернет магазин",
  • "paymentMethod": "ACQUIRING",
  • "paymentSystem": "MIR",
  • "cardNumber": "22013311****3339",
  • "expirationDate": "2035-10"
}

Изменение подписки

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

Authorizations:
secretKey
path Parameters
publicId
required
string

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

id
required
string

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

Request Body schema: application/json
required
purpose
string (SubscriptionPurpose) ^[A-Za-zА-Яа-я0-9 ()!@\[\]#+=_\|.,-]+$

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

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

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

Responses

Request samples

Content type
application/json
{
  • "purpose": "string",
  • "autoCharge": {
    }
}

Response samples

Content type
application/json
Example
{
  • "id": "subscription-test",
  • "status": {
    },
  • "purpose": "Подписка на интернет магазин",
  • "paymentMethod": "ACQUIRING",
  • "paymentSystem": "MIR",
  • "cardNumber": "22013311****3339",
  • "expirationDate": "2035-10"
}

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

Метод позволяет отменить подписку. После отмены проведение списаний по подписке будет недоступно. Отменить можно подписку только в статусе SUBSCRIBED.

Authorizations:
secretKey
path Parameters
publicId
required
string

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

id
required
string

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

Responses

Response samples

Content type
application/json
{
  • "code": "ERROR.BAD_REQUEST",
  • "message": "Действие недопустимо",
  • "traceId": "abb066c61a7c8b74af83f245c7706813"
}

Методы API

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

  • открытия платежной формы с использованием HTTP запросов;
  • получения информации о статусе заказа.

Получение информации о статусе транзакции

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

Authorizations:
secretKey
path Parameters
orderId
required
string <= 40 characters

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

Responses

Response samples

Content type
application/json
Example
{
  • "code": "SUCCESS",
  • "transaction": {
    }
}

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

Метод позволяет выполнить отмену/возврат по платежу, как полную, так и частичную. В случае с СБП выполняется только возврат.

Для мерчантов с подключенной фискализацией метод также позволяет сформировать фискальный чек по возврату. Для этого необходимо в теле запроса передать данные чека в объекте receipt, чек возврата будет сформирован автоматически.

Authorizations:
secretKey
path Parameters
orderId
required
string <= 40 characters

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

refundId
required
string

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

Request Body schema: application/json
One of
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

Request samples

Content type
application/json
Example
{
  • "amount": 1200,
  • "paymentDetails": "Покупка в магазине №1"
}

Response samples

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

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

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

Authorizations:
secretKey
path Parameters
orderId
required
string <= 40 characters

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

refundId
required
string

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

Responses

Request samples 

<?php

$orderId = 'order-test';
$refundId = 'refund-test';

/** @var \Raiffeisen\Ecom\Client $client */
$response = $client->getOrderRefund($orderId, $refundId);

print_r($response);

?>

Response samples

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

Получение информации о заказе

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

Authorizations:
secretKey
path Parameters
orderId
required
string <= 40 characters

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

Responses

Request samples 

<?php

$orderId = 'order-test';

/** @var \Raiffeisen\Ecom\Client $client */
$response = $client->getOrder($orderId);

print_r($response);

?>

Response samples

Content type
application/json
{
  • "amount": 12500.5,
  • "comment": "Покупка шоколадного торта",
  • "extra": {
    },
  • "status": {
    },
  • "expirationDate": "2024-12-31T17:00:00+03:00"
}

Отмена выставленного заказа

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

Authorizations:
secretKey
path Parameters
orderId
required
string <= 40 characters

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

Responses

Request samples 

<?php

$orderId = 'order-test';

/** @var \Raiffeisen\Ecom\Client $client */
$client->deleteOrder($orderId);

?>

Response samples

Content type
application/json
{
  • "code": "string",
  • "message": "string"
}

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

Метод позволяет получить по заказу список чеков, которые успешно зарегистрированы в ОФД и имеют статус DONE. По умолчанию возвращаются как чеки прихода, так и чеки возврата. Чтобы получить чеки определенного типа, необходимо в строке запроса передать дополнительный параметр receiptType.
Если ни один чек не найден, в ответ вернется 200 OK и пустой массив.

Authorizations:
secretKey
path Parameters
orderId
required
string <= 40 characters

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

query Parameters
receiptType
string

Тип чека:

  • SELL – чек прихода
  • REFUND – чек возврата'

Responses

Request samples 

<?php

$orderId = 'order-test';

/** @var \Raiffeisen\Ecom\Client $client */
$response = $client->getOrderReceipts($orderId);

print_r($response);

?>

Response samples

Content type
application/json
Example
[
  • {
    }
]

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

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

Authorizations:
secretKey
path Parameters
orderId
required
string <= 40 characters

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

refundId
required
string

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

Responses

Request samples 

<?php

$orderId = 'order-test';
$refundId = 'refund-test';

/** @var \Raiffeisen\Ecom\Client $client */
$response = $client->getOrderRefundReceipt($orderId, $refundId);

print_r($response);

?>

Response samples

Content type
application/json
{
  • "receiptNumber": "3000827351831",
  • "receiptType": "REFUND",
  • "status": "DONE",
  • "orderNumber": "order-test",
  • "total": 1200,
  • "ofdUrl": "https://lk.platformaofd.ru/web/noauth/cheque?fn=7284440500012345&fp=1702712345&i=1234",
  • "ofdDocumentNumber": 133,
  • "ofdDocumentAttribute": "3449555941",
  • "timezone": "string",
  • "onlinePayment": true,
  • "customer": {
    },
  • "items": [
    ],
  • "payments": [
    ],
  • "additionalUserProperty": {
    }
}

Уведомления

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

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

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

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

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

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

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

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

Необходимо проверять сумму, так как у клиентов есть возможность ее изменить.

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

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

header Parameters
X-Api-Signature-SHA256
required
string

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

Request Body schema: application/json
event
required
string
Value: "PAYMENT"

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

required
any

Данные по операции

Request samples

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

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

header Parameters
X-Api-Signature-SHA256
required
string

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

Request Body schema: application/json
One of
object

Request samples

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

Уведомление о подписке Webhook

header Parameters
X-Api-Signature-SHA256
required
string

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

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

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

required
any

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

Request samples

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

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

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

Тип операции

any (Transaction)

Данные по операции

Request samples

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

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

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

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

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

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

Реестр

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

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

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

Наименование колонки Значение
Мерчант Идентификатор в системе банка
Дата операции МСК Дата и время проведения операции
Тип Тип операции
id заказа Id заказа в системе партнера (orderId)
id возврата Id возврата в системе партнера (refundId)
Комментарий Комментарий к заказу (comment)
Способ оплаты Instant Payment QR - при оплате по СБП, Название платежной системы - по Эквайрингу
Данные оплаты QR id - для СБП, authCode и rnn -для Эквайринга
id клиента СБП - маскированный код плательщика. Для Эквайринга - маскированный номер карты
Сумма Сумма транзакции (amount)
Комиссия Комиссия по транзакции
Дополнительные поля Дополнительная информация (extra)

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

Выписка

Пример выписки по платежам интернет-эквайринга:
Download PDF

Пример выписки по форме 2в1 (интернет-эквайринг и СБП):

Download PDF Download 1C Download XML

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

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

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

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

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

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.

operationTypes
string
Enum: "Payment" "Refund"

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

qrId
string
Example: qrId=AD1F2CD7212E48FA919AB52EF0AEFB33

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

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.

operationTypes
string
Enum: "Payment" "Refund"

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

qrId
string
Example: qrId=AD1F2CD7212E48FA919AB52EF0AEFB33

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

Responses

Response samples

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

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

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

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

code message
ERROR.NOT_FOUND Счет не найден у данного партнера
ERROR.REFUND_INSUFFICIENT_FUNDS Сумма возврата больше суммы остатка по платежу
ERROR.INVALID_REQUEST Некорректные параметры запроса
RECEIPT_VALIDATION_FAILED Чек не прошел валидацию. Причина: *

Описание ошибок при работе с платежной формой клиента:

code message http code
ERROR.BAD_REQUEST Платёж с данным идентификатором уже существует 400
ERROR.BAD_REQUEST Некорректное значение поля: %s %s 400
ERROR.BAD_REQUEST Тело запроса некорректно 400
Отсутствует 401
ERROR.FORBIDDEN Доступ запрещен 403
ERROR.PAYMENT_NOT_FOUND Платеж не найден 404
ERROR.INTERNAL_ERROR Внутренняя ошибка сервиса 500

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

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

Дата Описание
02.09.2025 * Добавлен сценарий работы с подпиской
01.09.2025 * В фискальные чеки добавлены поля timezone (тег 1011, для ФФД 1.2), onlinePayment (тег 1125) и plannedStatus (тег 2003)
10.08.2025 * Добавлен метод формирования заказа с получением короткой ссылки
20.05.2025 * Добавлен ФФД 1.2 для сервиса "Модулькасса" и обновлена инструкция подключения фискализации
14.02.2025 * Добавлен ФФД 1.2 для сервиса "Orange Data" и обновлена инструкция подключения фискализации
24.07.2024 * Объединена документация для чеков по ФФД 1.05 и ФФД 1.2
10.07.2024 * Добавлены уведомления на операции возвратов
18.04.2024 * В методы сверок операций за период добавлен новый параметр комиссия
29.03.2023 * Внесены ограничения по полям comment при создании заказов и paymentDetails при возвратах
16.12.2022 * Добавлены методы для сверки операций по картам и СБП
11.10.2022 * Добавлены SDK с описанием в методах
30.09.2022 * Реализована поддержка авансовых чеков и чеков частичной предоплаты
26.08.2022 * Добавлен ФФД 1.2 для сервиса "АТОЛ Онлайн"
29.07.2022 * Изменены хосты :
* Боевой с e-commerce.raiffeisen.ru на pay.raif.ru
* Тестовый c ecom.test.raiffeisen.ru на pay-test.raif.ru
27.07.2022 * Добавлен параметр paymentDetails, позволяет указать назначение платежа для вашей выписки для операций СБП
30.05.2022 * Добавлен параметр successSbpUrl, который позволяет передать ссылку для перенаправления клиента, из приложения банка, в случае успешной операции
17.05.2022 * Добавлен метод открытия платежной формы через POST-метод
15.04.2022 * В документацию добавлен партнер "БИФИТ", приведена инструкция по подключению онлайн-кассы сервиса БИФИТ
* Скорректированы примеры запроса на сохранение чека (удалены параметры для агентских операций)
* Дополнено правило заполнения номенклатурного кода для партнера "БИФИТ"
* Небольшие правки по тексту
25.03.2022 * В модель чека добавлен параметр paymentMode для передачи способа расчёта (100% предоплата, полный расчет)
05.03.2022 * Расширен API для оформления возврата для возможности пробить чек. В т.ч. в POST-метод добавлен новый объект receipt для передачи данных чека
* Добавлен API для получения массива чеков по заказу
* Добавлен API для получения чека возврата по заказу и идентификатору возврата
* Реализовано переключение через кнопки "с чеком/без чека" для API, где возможен один из вариантов
* Добавлен перевод документации на английский язык
18.01.2022 * Для фискализации в чек прихода добавлены новые параметры для агентских операций: agentType, supplierInfo
30.12.2021 * Обновлена диаграмма последовательности UML в разделе "Схема работы"
29.10.2021 * Добавлены методы для отмены заказа и получения его статуса
21.10.2021 * Добавлен параметр expirationDate - отвечающий за срок жизни заказа