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 для ввода данных платежа и передать сложную структуру данных
  • Редирект клиента на платежную страницу Райффайзенбанка

Схема работы

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

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

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

В процессе платежа пользователь совершает следующие действия:

  • Пользователь выбирает товары/услуги в корзину магазина и нажимает на кнопку "Оплатить"
  • Партнер открывает платежную форму
  • Пользователь вводит реквизиты на платежной форме и подтверждает платеж

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

Сценарий проведения платежа

Данная схема работы требует наличие сертификации PCI DSS у вашей компании

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

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

Для проведения платежа первоначально необходимо создать платеж с помощью метода [Создание платежа]. В результате выполнения метода платеж будет сформирован в системе Банка. В ответе метода вернется объект платежа со статусом NEW.

  • Вместе с объектом платежа могут вернуться дополнительные параметры, необходимые для выполнения дополнительного шага [3DS Method].

2. Продолжение платежа

После того, как платеж был создан, необходимо продолжить обработку платежа с помощью метода [Продолжение платежа].

  • В некоторых случаях метод может завершить платеж (перевести его в финальный статус SUCCESS), если оплата пройдет по 3DS v.2 frictionless flow.

3. Вызов ACS эмитента для прохождения 3DS и ввода OTP-кода пользователем

Если в результате выполнения метода метода [Продолжение платежа] вернулся статус 3DS_PENDING, мерчанту необходимо перенаправить плательщика на страницу авторизации Банка-эмитента, а также отправить POST-запрос в сервис аутентификации эмитента.

  • Адрес Банка-эмитента вернется в параметре acsUrl
  • Параметры, необходимые для отправки в запросе зависят от версии 3DS

3DS v.1:

Параметр Описание
MD Информация для идентификации платежа. Параметр возвращается в ответе метода [Продолжение платежа].
PaReq Параметр, необходимый для аутентификации плательщика. Параметр возвращается в ответе метода [Продолжение платежа].
TermUrl URL-адрес на стороне мерчанта, на который ACS вернет ответ после прохождения 3DS. Также на данный адрес будет перенаправлен плательщик после успешного ввода OTP-кода.

3DS v.2:

Параметр Описание
creq Данные платежной сессии, необходимые для проведения 3DS аутентификации. Параметр возвращается в ответе метода [Продолжение платежа].

Пример отправки POST-запроса в сторону ACS эмитента, для продолжения 3DS v.2:

  export function createContinuePayment3ds2Iframe(acsUrl, creq) {
    const container = document.getElementById('otp-page');
    const iframe = window.document.createElement('iframe');
    iframe.id = 'threeDs-2-iframe';
    iframe.style = 'height: 100%; width: 100%; overflow: hidden; position: absolute; top: 0; left: 0; background: white; z-index: 1000; border: none;';
    const html = `
      <body>
        <div>
          <form name="form" action="${acsUrl}" method="post">
            <input type="hidden" name="creq" value="${creq}">
          </form>
        </div>
      </body>
      <script>
        window.document.form.submit();
      </script>
    `;
    container.appendChild(iframe);
    iframe.contentWindow.document.open();
    iframe.contentWindow.document.write(html);
  }

После вызова ACS и успешного ввода OTP-кода пользователем, на termUrl мерчанта поступит входящий запрос от эмитента с параметрами cres (в случае 3DS v.2 challenge), либо pares и md в случае 3DS v.1.

Пример получения pares через подписку и прослушивания post-message:

  window.addEventListener('message', (event) => {
    try {
      if (typeof event.data !== 'string') return;
      const { pares } = JSON.parse(event.data);
      // Вызываем необходимый метод подтверждения 3DS для завершения платежа
    } catch (error) {
      console.error('Ошибка при обработке message:', error);
    }
  });

4. Подтверждение 3DS и завершение платежа

Для завершения оплаты необходимо завершить обработку платежа, используя методы [Подтверждение 3DS v.1], либо [Подтверждение 3DS v.2].

Пример с завершением платежа по 3DS v.1:

window.parent.postMessage(JSON.stringify({
  pares: paRes
}), '*');

Пример с завершением платежа по 3DS v.2:

window.parent.postMessage(JSON.stringify({
  cres: document.getElementById('data').dataset.cres,
}), '*');

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

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

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

Поставщик кассового оборудования ФФД 1.05 ФФД 1.2
АТОЛ Онлайн + +
Билайн - +
БИФИТ + -
Чек-Онлайн + -
Эвотор + +
LIFE PAY + +
ОFD.ru + +
Orange Data + +
Модулькасса - +

АТОЛ Онлайн

Поддерживает ФФД 1.05 и ФФД 1.2

  1. Зарегистрируйтесь в сервисе "АТОЛ Онлайн" и подключите онлайн-кассу
  2. Заключите договор с оператором фискальных данных
  3. Зайдите в личный кабинет "АТОЛ Онлайн", чтобы получить логин, пароль и идентификатор. Выберите раздел "Мои компании", нажмите кнопку "Настройки интегратора". Скачается XML-файл с настройками, найдите в файле элемент access, в нём будут все три параметра: login, password, group_code. Если возникли трудности, обратитесь в техподдержку "АТОЛ Онлайн".
  4. Подключите фискализацию в Личном кабинете Raif Pay или RBO
    В Личном кабинете Raif Pay: Настройки → Фискализация чеков → Подключить
    В RBO: Прием платежей → Настройки → Фискализация чеков → Подключить
  5. Убедитесь, что при вызове платежной формы передаются данные, необходимые для формирования чека (см. объект receipt в методе создания заказа при открытии формы)

Билайн

Поддерживает ФФД 1.2

  1. Зарегистрируйтесь в сервисе “Облачные кассы Билайн” и подключите онлайн-кассу
  2. После подключения облачной кассы в личном кабинете Билайн запомните полученный логин и установленный пароль. Эти данные понадобятся на следующем шаге.
  3. Подключите фискализацию в Личном кабинете Raif Pay или RBO
    В Личном кабинете Raif Pay: Настройки → Фискализация чеков → Подключить
    В RBO: Прием платежей → Настройки → Фискализация чеков → Подключить
    Для идентификатора группы ККТ используйте название “ecom”. После этого чеки будут автоматически регистрироваться через выбранную кассу. Помимо автоматической фискализации чеков также доступна фискализация через API банка.

БИФИТ

Поддерживает ФФД 1.05

  1. Заключите договор с БИФИТ на аренду ККТ
  2. Оплатите аренду ККТ и ФН. БИФИТ предоставит бесплатное подключение к ОФД Яндекс. При необходимости можно подключиться к другому ОФД. Для этого в ЛК найдите № ККТ и № ФН и выполните регистрацию в ОФД на свой выбор
  3. Перейдите в личный кабинет БИФИТ для получения данных по подключенной кассе. Откройте пункт меню «Бифит Онлайн» и перейдите в раздел «Коннекторы ККТ». Создайте токен коннектора и привяжите к нему кассу. Скопируйте токен коннектора и заводской номер ККТ (идентификатор ККТ)
  4. Подключите фискализацию в Личном кабинете Raif Pay или RBO
    В Личном кабинете Raif Pay: Настройки → Фискализация чеков → Подключить
    В RBO: Прием платежей → Настройки → Фискализация чеков → Подключить
  5. Убедитесь, что при вызове платежной формы передаются данные, необходимые для формирования чека (см. объект receipt в методе создания заказа при открытии формы)

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

Чек-Онлайн

Поддерживает ФФД 1.05

  1. Зарегистрируйтесь в сервисе "Чек-Онлайн" и подключите онлайн-кассу
  2. Заключите договор с оператором фискальных данных
  3. Зайдите в личный кабинет клиента, чтобы получить логин и пароль. Откройте раздел "Предприятия", найдите в списке нужную компанию и нажмите на иконку в поле "Авторизация". Откроется раздел, в котором можно выбрать существующие логин и пароль или сгенерировать новые. Для получения идентификатора группы ККТ вернитесь в раздел "Предприятия" и выберите нужную компанию из списка. В открывшемся профиле предприятия скопируйте API Group ID. Эти данные понадобятся на следующем шаге.
  4. Подключите фискализацию в Личном кабинете Raif Pay или RBO
    В Личном кабинете Raif Pay: Настройки → Фискализация чеков → Подключить
    В RBO: Прием платежей → Настройки → Фискализация чеков → Подключить
  5. Убедитесь, что при вызове платежной формы передаются данные, необходимые для формирования чека (см. объект receipt в методе создания заказа при открытии формы)

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

Эвотор

Поддерживает ФФД 1.05 и ФФД 1.2

  1. Оставьте заявку на облачную онлайн-кассу на сайте Эвотор
  2. После подключения облачной кассы зайдите в личный кабинет Эвотор и получите приветственное письмо на E-mail. В личном кабинете и в письме содержатся логин, пароль и идентификатор группы касс. Скопируйте эти данные.
  3. Подключите фискализацию в Личном кабинете Raif Pay или RBO
    В Личном кабинете Raif Pay: Настройки → Фискализация чеков → Подключить
    В RBO: Прием платежей → Настройки → Фискализация чеков → Подключить
  4. Убедитесь, что при вызове платежной формы передаются данные, необходимые для формирования чека (см. объект receipt в методе создания заказа при открытии формы)

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

LIFE PAY

Поддерживает ФФД 1.05 и ФФД 1.2

  1. Оставьте заявку на облачную онлайн-кассу по ссылке. В заявке в поле Продукт укажите "Облачная касса".
    Поля для ИНН, номера телефона, имени и E-mail обязательны к заполнению. В поле "Комментарий" при необходимости можно указать дополнительную информацию. Например, "Позвонить по заявке завтра после 14:00"
  2. После подключения облачной кассы зайдите в личный кабинет LIFE PAY → Настройки → Разработчикам. В этом разделе скопируйте API KEY
  3. Подключите фискализацию в Личном кабинете Raif Pay или RBO
    В Личном кабинете Raif Pay: Настройки → Фискализация чеков → Подключить
    В RBO: Прием платежей → Настройки → Фискализация чеков → Подключить
    В поле Логин укажите номер телефона в формате 7xxxxxxxxxx, а в поле Пароль - API KEY, скопированный ранее
  4. Убедитесь, что при вызове платежной формы передаются данные, необходимые для формирования чека (см. объект receipt в методе создания заказа при открытии формы)

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

OFD.ru

Поддерживает ФФД 1.05 и ФФД 1.2

  1. Подключите онлайн-кассу в сервисе OFD.ru
  2. Зарегистрируйте кассу в ФНС через сервис Ferma по инструкции

Для получения данных по подключенной кассе в OFD.ru перейдите в раздел Ferma в личном кабинете клиента и пролистайте до виджета "Реквизиты доступа". Скопируйте логин, пароль и идентификатор группы ККТ для подключения. Эти данные понадобятся на следующем шаге.

  1. Подключите фискализацию в Личном кабинете Raif Pay или RBO
    В Личном кабинете Raif Pay: Настройки → Фискализация чеков → Подключить
    В RBO: Прием платежей → Настройки → Фискализация чеков → Подключить
  2. Убедитесь, что при вызове платежной формы передаются данные, необходимые для формирования чека (см. объект receipt в методе создания заказа при открытии формы)

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

Orange Data

Поддерживает ФФД 1.05 и ФФД 1.2

  1. Зарегистрируйтесь в системе “Orange Data” и подключите онлайн-кассу
  2. В разделе “Интеграция” ЛК Orange Data сгенерируйте файлы сертификации и пару ключей RSA.
  3. Для получения логина и пароля направьте следующие данные на E-mail api@orangedata.ru с указанием темы письма "Запрос данных Райффайзен Банк":
  • ИНН
  • Файл сертификата .pfx, private_key.xml и public_key.xml, созданные на шаге 2.
  • Если Вы работаете с новыми ставками НДС 5%, 5/105%, 7%, 7/107%, то сообщите об этом в данном письме. На кассу будет установлено необходимое ПО.
  1. Подключите фискализацию в Личном кабинете Raif Pay или RBO
    В Личном кабинете Raif Pay: Настройки → Фискализация чеков → Подключить
    В RBO: Прием платежей → Настройки → Фискализация чеков → Подключить
    Для идентификатора группы ККТ используйте название “Main” для ФФД 1.05 и “Main_2” для ФФД 1.2.
  2. Убедитесь, что при вызове платежной формы передаются данные, необходимые для формирования чека (см. объект receipt в методе создания заказа при открытии формы)

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

Модулькасса

Поддерживает ФФД 1.2

  1. Оставьте заявку на облачную онлайн-кассу по ссылке
  2. После оплаты счета мы зарегистрируем кассу в ФНС, настроим и подключим к ОФД
  3. После подключения облачной кассы зайдите в личный кабинет Модулькассы и создайте точку продаж по инструкции
    Если точка уже создана, то включите функцию приема чеков интернет-магазина:
  • Выберите точку продаж, к которой хотите подключить интернет-магазин;
  • Нажмите на точку продаж и включите функцию «Использовать для документов интернет магазина»;
  • В окне редактирования скопируйте значение из поля "Идентификатор" - оно понадобится для подключения интеграции, его лучше сохранить в отдельном текстовом файле.
  1. Получите логин и пароль для подключения интеграции:
  • Нажмите «Настройки» в верхнем правом углу;
  • Перейдите в раздел «Сервисы»;
  • Активируйте ползунок «Чеки интернет-магазина»;
  • В новом окне появятся специальные логин и пароль для интеграции. Если эта комбинация вам не нравится, нажмите кнопку «Сгенерировать логин и пароль»;
  • Скопируйте логин и пароль отдельно в документ, где ранее сохранили идентификатор точки продаж.
  1. Подключите фискализацию в Личном кабинете Raif Pay или RBO
    В Личном кабинете Raif Pay: Настройки → Фискализация чеков → Подключить
    В RBO: Прием платежей → Настройки → Фискализация чеков → Подключить
    Для идентификатора группы ККТ используйте идентификатор точки продаж.

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

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

Эквайринг

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

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

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

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

PAN карты Срок действия карты CVV OTP код 3DS Сценарий
2201382000000039 12/35 880 3DS2 Frictionless
2201382000000021 12/35 880 1234 3DS2 Challenge
4000001000000018 12/35 880 1234 3DS1 Flow

СБП

Для полного цикла тестирования Райффайзенбанк предоставляет возможность использования демо-приложения для оплаты 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-_.]+$

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

amount
required
number

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

comment
string <URL encoded> <= 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

successUrl
string <uri>

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

failUrl
string <uri>

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

paymentMethod
string
Enum: "ONLY_SBP" "ONLY_ACQUIRING"

Метод оплаты

locale
string = 2 characters
Enum: "ru" "en"

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

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-z0-9-_.]+$

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

amount
required
number

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

comment
string <URL encoded> <= 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

successUrl
string <uri>

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

failUrl
string <uri>

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

object

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

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

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

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

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

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

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

successSbpUrl
string <uri>

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

paymentDetails
string <URL encoded> <= 140 characters

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

Responses

Request samples

Content type
application/json
Example
{
  • "publicId": "000001680200002-80200002",
  • "orderId": "string",
  • "amount": 1200.37,
  • "comment": "string",
  • "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": "string"
}

Response samples

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

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

Для работы с карточными платежами с вашей формой, потребуется PCI DSS сертификация вашей организации.

PCI DSS — стандарт информационной безопасности, принятый в индустрии платежных карт Visa и MasterCard. Соблюдать требования стандарта обязаны все компании, которые принимают оплату по картам на собственной платежной форме.
Для фискализации платежей можно использовать API фискализации банка Перед началом работы рекомендуется ознакомиться со сценарием проведения платежа: Сценарий проведения платежа.

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

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

Для мерчантов с наличием сертификата PCI DSS

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

Примечания:

  • Если в ответе метода вернулись дополнительные параметры acsUrl, threeDSMethodData, необходимо выполнить шаг [Прохождение 3DS Method].
  • Если дополнительные данные в ответе не вернулись, необходимо продолжать обработку платежа, используя метод [Продолжение платежа].
Authorizations:
secretKey
path Parameters
publicId
required
string

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

header Parameters
User-Agent
required
string

Содержимое http заголовкa User-Agent

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

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

amount
required
number > 0

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

object

Заказ

object

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

method
required
string (WhitelabelPaymentMethod)
Value: "CARD"

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

  • CARD - Оплата по карте
required
object

Данные плательщика

Responses

Request samples

Content type
application/json
{
  • "id": "payment-test",
  • "amount": 540,
  • "order": {
    },
  • "extra": {
    },
  • "method": "CARD",
  • "parameters": {
    }
}

Response samples

Content type
application/json
Example
{
  • "id": "payment-test",
  • "amount": 534.31,
  • "order": {
    },
  • "objectType": "CREATED_PAYMENT_3DS1",
  • "extra": {
    },
  • "method": "CARD",
  • "status": {
    }
}

Прохождение 3DS Method

Для мерчантов с наличием сертификата PCI DSS

Метод используется для выполнения шага 3DS Method в процессе аутентификации. Браузер плательщика должен отправить POST-запрос на acsUrl, предоставленный системой, с передачей параметра threeDSMethodData.

Примечания:

  • Данный запрос выполняется только из браузера плательщика.
  • acsUrl - Полный адрес, который необходимо вызвать из браузера плательщика. Параметр будет получен в результате выполнения метода [Создание платежа].
  • threeDSMethodData - JSON объект, закодированный в base64, содержащий информацию о транзакции, будет получен в результате выполнения метода [Создание платежа].
  • После выполнения метода необходимо продолжать обработку платежа, используя метод [Продолжение платежа].
Request Body schema: application/x-www-form-urlencoded
required
threeDSMethodData
required
string

JSON, закодированный в base64, содержащий информацию о транзакции

Responses

Request samples

Content type
application/x-www-form-urlencoded
threeDSMethodData=eyJ0aHJlZURTQ29tcEluZm8iOiAiZXhhbXBsZSJ9

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

Для мерчантов с наличием сертификата PCI DSS

Метод позволяет получить состояние платежа, а также необходимые данные для прохождения 3DS аутентификации на любом этапе оплаты.

Authorizations:
secretKey
path Parameters
publicId
required
string

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

id
required
string

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

Responses

Response samples

Content type
application/json
Example
{
  • "id": "payment-test",
  • "amount": 534.31,
  • "order": {
    },
  • "objectType": "CREATED_PAYMENT_3DS1",
  • "extra": {
    },
  • "method": "CARD",
  • "status": {
    }
}

Продолжение платежа

Для мерчантов с наличием сертификата PCI DSS

Метод используется для продолжения платежа. Метод также может завершить платеж в случае прохождения платежа по frictionless flow (3DS2).

Примечания:

  • В случае получения статуса 3DS_PENDING в ответе метода, необходимо отправить POST-запрос и перенаправить плательщика на ACS эмитента, подробнее данный шаг описан в [Сценарии проведения платежа].
  • После перенаправления плательщика на ACS эмитента, необходимо завершить платеж, используя методы [Подтверждение 3DS v.1], либо [Подтверждение 3DS v.2] с параметрами, полученными от эмитента.
Authorizations:
secretKey
path Parameters
publicId
required
string

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

id
required
string

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

Request Body schema: application/json
cresNotificationUrl
string

URL-адрес на стороне мерчанта, на который ACS вернет ответ после прохождения 3DS. Также на данный адрес будет перенаправлен плательщик после успешного ввода OTP-кода. Только для платежей, которые будут обработаны по 3DS v.2.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
Example
{
  • "id": "payment-test",
  • "amount": 534.31,
  • "order": {
    },
  • "objectType": "CONTINUE_PAYMENT_3DS1",
  • "extra": {
    },
  • "method": "CARD",
  • "status": {
    },
  • "parameters": {
    }
}

Подтверждение 3DS v.1

Для мерчантов с наличием сертификата PCI DSS

Метод используется для подтверждения 3DS v.1 и завершения платежа.

Вызывать метод необходимо при получении статуса 3DS_PENDING с передачей параметра pares, который будет получен от Банка-Эмитента через браузер плательщика.

Authorizations:
secretKey
path Parameters
publicId
required
string

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

id
required
string

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

Request Body schema: application/json
required
pares
required
string

Зашифрованный ответ от ACS эмитента с результатами 3DS авторизации, необходимыми для завершения платежа. Параметр должен быть получен браузером плательщика и передан в Райффайзенбанк.

Responses

Request samples

Content type
application/json
{
  • "pares": "eJzNWVmvo0iy/iutnkdUzW6bketImew2YLMaeGkBxixmM4tZfv3gc6qqq2tq5va9uiMNL0CQGRmRsXwRyd5K2zjmzDga2vhtr8ZdFyTxL9n186/Z9XfmFjLrh"
}

Response samples

Content type
application/json
{
  • "id": "payment-63853012",
  • "amount": 534.31,
  • "order": {
    },
  • "objectType": "FINAL_CARD_PAYMENT",
  • "extra": {
    },
  • "method": "CARD",
  • "status": {
    },
  • "parameters": {
    }
}

Подтверждение 3DS v.2

Для мерчантов с наличием сертификата PCI DSS

Метод используется для подтверждения 3DS v.2 и завершения платежа.

Вызывать метод необходимо при получении статуса 3DS_PENDING с передачей параметра cres, который будет получен от Банка-Эмитента через браузер плательщика.

Authorizations:
secretKey
path Parameters
publicId
required
string

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

id
required
string

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

Request Body schema: application/json
required
cres
required
string

Зашифрованный ответ от ACS эмитента с результатами 3DS авторизации, необходимыми для завершения платежа. Параметр должен быть получен браузером плательщика и передан в Райффайзенбанк.

Responses

Request samples

Content type
application/json
{
  • "cres": "eJzNWVmvo0iy/iutnkdUzW6bketImew2YLMaeGkBxixmM4tZfv3gc6qqq2tq5va9uiMNL0CQGRmRsXwRyd5K2zjmzDga2vhtr8ZdFyTxL9n186/Z9XfmFjLrh"
}

Response samples

Content type
application/json
{
  • "id": "payment-63853012",
  • "amount": 534.31,
  • "order": {
    },
  • "objectType": "FINAL_CARD_PAYMENT",
  • "extra": {
    },
  • "method": "CARD",
  • "status": {
    },
  • "parameters": {
    }
}

Методы 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",
  • "customer": {
    },
  • "items": [
    ],
  • "payments": [
    ]
}

Уведомления

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

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

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

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

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

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

Для проверки подлинности уведомления по оплате к данным добавляется подпись в заголовке x-api-signature-sha256, полученная на основе общего секретного ключа и контрольной строки amount|publicId|order|transaction.status.value|transaction.status.date с помощью HMAC-SHA-256.

Для проверки подлинности уведомления по возврату к данным добавляется подпись в заголовке x-api-signature-sha256, полученная на основе общего секретного ключа и контрольной строки amount|publicId|refund.id|status.value|status.date с помощью HMAC-SHA-256.

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

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

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

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

Тип операции

any (Transaction)

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

Request samples

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

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

Request Body schema: application/json
One of
object

Request samples

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

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

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

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

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

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{}

Реестр

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

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

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

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

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

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

Выписка

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

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

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

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

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

Authorizations:
secretKey
query Parameters
from
required
string <ENCODE 'YYYY-MM-DDТHH24:MM:SS±HH:MM'>

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

to
required
string <ENCODE 'YYYY-MM-DDТHH24:MM:SS±HH:MM'>

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

operationTypes
string
Enum: "Payment" "Refund"

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

qrId
string
Example: qrId=AD1F2CD7212E48FA919AB52EF0AEFB33

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

Responses

Response samples

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

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

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

Authorizations:
secretKey
query Parameters
from
required
string <ENCODE 'YYYY-MM-DDТHH24:MM:SS±HH:MM'>

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

to
required
string <ENCODE 'YYYY-MM-DDТHH24:MM:SS±HH:MM'>

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

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.

Дата Описание
20.05.2025 * Добавлен ФФД 1.2 для сервиса "Модулькасса" и обновлена инструкция подключения фискализации
14.02.2025 * Добавлен ФФД 1.2 для сервиса "Orange Data" и обновлена инструкция подключения фискализации
19.12.2024 * Добавлены методы по работе с формой клиента
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 - отвечающий за срок жизни заказа