Raiff logo
API docs by Redocly

Raiffeisenbank e-commerce API (1.0)

Download OpenAPI specification:Download

Support e-mail: ecom@raiffeisen.ru

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

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

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

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

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

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

Схема работы

Проведение платежа на форме клиента

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

Данная схема работы требует наличие сертификации 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,
}), '*');

Интеграция

Взаимодействие осуществляется по протоколу 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

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

Для полного цикла тестирования оплаты необходимо указывать сумму платежа больше 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

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

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

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

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

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

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

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

Примечания:

  • Если в ответе метода вернулись дополнительные параметры acsUrl, threeDSMethodData, необходимо выполнить шаг [Прохождение 3DS Method].
  • Если дополнительные данные в ответе не вернулись, необходимо продолжать обработку платежа, используя метод [Продолжение платежа].
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

Заказ

object

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

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

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

subscriptionId
required
string^[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": "CARD",
  • "parameters": {
    }
}

Response samples

Content type
application/json
Example
{
  • "id": "payment-test",
  • "amount": 534.31,
  • "order": {
    },
  • "objectType": "CREATED_PAYMENT_3DS1",
  • "extra": {
    },
  • "flow": "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^[A-Za-z0-9-_.]+$

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

Responses

Response samples

Content type
application/json
Example
{
  • "id": "payment-test",
  • "amount": 534.31,
  • "order": {
    },
  • "objectType": "CREATED_PAYMENT_3DS1",
  • "extra": {
    },
  • "flow": "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^[A-Za-z0-9-_.]+$

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

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": {
    },
  • "flow": "CARD",
  • "status": {
    },
  • "parameters": {
    }
}

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

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

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

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

Authorizations:
secretKey
path Parameters
publicId
required
string

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

id
required
string^[A-Za-z0-9-_.]+$

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

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
Example
{
  • "id": "payment-test",
  • "amount": 534.31,
  • "order": {
    },
  • "objectType": "FINAL_CARD_PAYMENT",
  • "extra": {
    },
  • "flow": "CARD",
  • "status": {
    },
  • "parameters": {
    }
}

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

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

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

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

Authorizations:
secretKey
path Parameters
publicId
required
string

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

id
required
string^[A-Za-z0-9-_.]+$

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

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
Example
{
  • "id": "payment-test",
  • "amount": 534.31,
  • "order": {
    },
  • "objectType": "FINAL_CARD_PAYMENT",
  • "extra": {
    },
  • "flow": "CARD",
  • "status": {
    },
  • "parameters": {
    }
}

Расширение сценариев

В данном разделе описаны методы, расширяющие сценарий проведения платежа.

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

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

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

Authorizations:
secretKey
path Parameters
orderId
required
string <= 40 characters ^[A-Za-z0-9-_.]+$

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

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

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

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 ^[A-Za-z0-9-_.]+$

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

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

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

Responses

Response samples

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

Реестр

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

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

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

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

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

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

Выписка

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

Уведомления

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

Также адрес для тестовой и боевой среды можно указать с помощью метода в 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

Уведомления отправляются с 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
{
  • "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": {
    }
}

Настройка 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
{}

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

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

Дата Описание
22.08.2025 Добавлены методы по работе с формой клиента