Raiffeisenbank e-commerce API (1.0)

Download OpenAPI specification:Download

Support e-mail: ecom@raiffeisen.ru

Свои предложения и идеи о документации можно оставить в репозитории по адресу: https://github.com/Raiffeisen-DGTL/ecom-API/blob/master/ecom.yaml

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

Для подключения перейдите на сайт.

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

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

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

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

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

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

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

Cхема работы

Демонстрация: https://pay.raif.ru/pay/demo.html

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

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

Схема выполнения платежа представлена ниже:

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

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

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

АТОЛ Онлайн

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

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

OFD.ru

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

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

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

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

Чек-Онлайн

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

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

БИФИТ

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

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

LIFE PAY

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

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

Эвотор

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

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

Билайн

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

Orange Data

  1. Зарегистрируйтесь в системе “Orange Data” и подключите онлайн-кассу
  2. В разделе “Интеграция” ЛК Orange Data сгенерируйте файлы сертификации и пару ключей RSA.
  3. Для получения логина и пароля направьте следующие данные на E-mail api@orangedata.ru с указанием темы письма "Запрос данных Райффайзен Банк":
  • ИНН
  • Файл сертификата .pfx и private_key.xml, созданные на шаге 2.
  1. Подключите фискализацию в Личном кабинете Raif Pay или RBO
    В Личном кабинете Raif Pay: Настройки → Фискализация чеков → Подключить
    В RBO: Прием платежей → Настройки → Фискализация чеков → Подключить
    Для идентификатора группы ККТ используйте название “main”."

API

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

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

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

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

Авторизация

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

  • publicId - идентификатор, который используется для открытия платежной формы и не является конфиденциальным.
  • secretKey - секретный ключ, который используется для межсервисного взаимодействия.

Продовый хост: https://pay.raif.ru

Тестовый хост: https://pay-test.raif.ru

BАЖНО: Секретный ключ необходимо хранить в защищенном месте, нельзя публиковать на сторонних ресурсах или передавать третьим лицам.

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

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

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

Параметры ошибок

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

HTTP-код code message Комментарий
200 SUCCESS Запрос обработан успешно Успешное выполнение запроса без логических и системных сбоев.
200 ERROR.Код_ошибки Текстовое сообщение о сути ошибки Логическая ошибка при выполнении запроса.
500 ERROR.INTERNAL Ошибка Системная ошибка при выполнении запроса.

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

Эквайринг

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

  • 4000001000000018 12/24 880 - с 3DS пин для успешной оплаты 1234, для получения ошибки 1111

СБП

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

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

SDK

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

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

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

Доступные SDK:

  • JS - позволяет открывать форму с фронтовой части.
  • PHP
  • NODE
  • JAVA

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

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

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

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

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

При редиректе клиента на полученный URL откроется форма для оплаты

query Parameters
publicId
required
string

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

amount
required
string

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

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

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

comment
string <URL encoded> <= 140 characters

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

paymentDetails
string <= 140 characters

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

paymentMethod
string
Enum: "ONLY_SBP" "ONLY_ACQUIRING"

Выбор метода оплаты

locale
string
Enum: "ru" "en"

Выбор языка формы, по умолчанию ru

successUrl
string <URL encoded>

URL ресурса, куда будет перенаправлен клиент в случае успешного платежа

failUrl
string <URL encoded>

URL ресурса, куда будет перенаправлен клиент в случае неуспешного платежа

expirationDate
string <date-time encoded>

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

successSbpUrl
string <uri>

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

Responses

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

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

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

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

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

Order ID

amount
required
number

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

comment
string <= 140 characters

Комментарий. Не может быть пустым или содержать только пробелы. Может сождержать:
• Символы латинского алфавита (A–Z и a–z) с десятичными кодами из диапазонов [065-090] и [097-122] в кодировке UTF-8;
• Символы русского алфавита (А-Я и а-я) с десятичными кодами из диапазона [1040-1103] в кодировке UTF-8;
• Цифры 0-9 с десятичными кодами из диапазона [048-057] в кодировке UTF-8;
• Специальные символы с десятичными кодами из диапазонов [032-047], [058-064], [091-096], [123-126] в кодировке UTF-8; - Символ «№» под номером 8470 в кодировке UTF-8

successUrl
string

URL ресурса, куда будет перенаправлен клиент в случае успешного платежа

failUrl
string

URL ресурса, куда будет перенаправлен клиент в случае неуспешного платежа

object

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

paymentMethod
string
Enum: "ONLY_SBP" "ONLY_ACQUIRING"

Выбор метода оплаты. Если значение не передано, отображается общая форма

locale
string
Enum: "ru" "en"

Выбор языка формы, по умолчанию ru

expirationDate
string <date-time>

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

successSbpUrl
string <uri>

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

paymentDetails
string <= 140 characters

Назначение платежа для платежей по СБП

Responses

Request samples

Content type
application/json
Example
{
  • "publicId": "000001680200002-80200002",
  • "orderId": "orderTest",
  • "amount": 1200,
  • "comment": "Покупка шоколадного торта",
  • "failUrl": "string",
  • "extra": {
    • "apiClient": "Payform Software",
    • "apiClientVersion": "1.0.0"
    },
  • "paymentMethod": "ONLY_SBP",
  • "locale": "ru",
  • "expirationDate": "2022-10-21T14:17:00.000+03:00",
  • "successSbpUrl": "https://bfkh.ru/",
  • "paymentDetails": "string"
}

Response samples

Content type
application/json
{
  • "timestamp": "2023-02-15T06:36:32.418+00:00",
  • "status": 415,
  • "error": "Unsupported Media Type",
  • "path": "string"
}

Методы API

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

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

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

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

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

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

header Parameters
Authorization
required

Responses

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

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

any (transaction)

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

Request samples

<?php

$orderId = 'testOrder';

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

print_r($response);

?>

Response samples

Content type
application/json
Example
{
  • "code": "SUCCESS",
  • "transaction": {
    • "id": 120059,
    • "orderId": "testOrder",
    • "status": {
      • "value": "SUCCESS",
      • "date": "2019-07-11T17:45:13+03:00"
      },
    • "paymentMethod": "acquiring",
    • "paymentParams": {
      • "rrn": 935014591810,
      • "authCode": "259AA"
      },
    • "amount": 12500.5,
    • "comment": "Покупка шоколадного торта",
    • "extra": {
      • "apiClient": "Payform Software",
      • "apiClientVersion": "1.0.0"
      }
    }
}

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

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

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

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

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

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

header Parameters
Authorization
required
Request Body schema: application/json
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

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

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

amount
number

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

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

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

ФФД 1.05 (object) or ФФД 1.2 (object) (Типы ФФД)

Данные чека
Объект передается в ответе, только если подключена фискализация и чек был передан в запросе на возврат

Request samples

Content type
application/json
Example
{
  • "amount": 1200,
  • "paymentDetails": "string"
}

Response samples

Content type
application/json
{
  • "code": "SUCCESS",
  • "amount": 1200,
  • "refundStatus": "IN_PROGRESS",
  • "receipt": {
    • "customer": {
      • "email": "customer@test.ru",
      • "name": "Иванов Иван Иванович"
      },
    • "items": [
      • {
        • "name": "Шоколадный торт",
        • "price": 1200,
        • "quantity": 1,
        • "amount": 1200,
        • "paymentObject": "COMMODITY",
        • "paymentMode": "FULL_PAYMENT",
        • "measurementUnit": "шт",
        • "nomenclatureCode": "00 00 00 01 00 21 FA 41 00 23 05 41 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 12 00 AB 00",
        • "vatType": "VAT20",
        • "agentType": "ANOTHER",
        • "supplierInfo": {
          • "phone": "+79991234567",
          • "name": "ООО «Ромашка»",
          • "inn": "956839506500"
          }
        }
      ],
    • "payments": [
      • {
        • "type": "PREPAID",
        • "amount": 1200
        }
      ]
    }
}

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

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

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

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

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

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

header Parameters
Authorization
required

Responses

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

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

amount
number

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

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

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

Request samples

<?php

$orderId = 'testOrder';
$refundId = 'testRefund';

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

print_r($response);

?>

Response samples

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

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

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

path Parameters
orderId
required
string

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

header Parameters
Authorization
required

Responses

Response Schema: application/json
amount
number <float>

Сумма заказа

comment
string

Комментарий. Не может быть пустым или содержать только пробелы. Может сождержать:
• Символы латинского алфавита (A–Z и a–z) с десятичными кодами из диапазонов [065-090] и [097-122] в кодировке UTF-8;
• Символы русского алфавита (А-Я и а-я) с десятичными кодами из диапазона [1040-1103] в кодировке UTF-8;
• Цифры 0-9 с десятичными кодами из диапазона [048-057] в кодировке UTF-8;
• Специальные символы с десятичными кодами из диапазонов [032-047], [058-064], [091-096], [123-126] в кодировке UTF-8; - Символ «№» под номером 8470 в кодировке UTF-8

object

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

object
expirationDate
string <date-time>

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

Request samples

<?php

$orderId = 'testOrder';

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

print_r($response);

?>

Response samples

Content type
application/json
{
  • "amount": 12500.5,
  • "comment": "Покупка шоколадного торт",
  • "extra": {
    • "apiClient": "Payform Software",
    • "apiClientVersion": "1.0.0"
    },
  • "status": {
    • "value": "NEW",
    • "date": "2019-08-24T14:15:22+03:00"
    },
  • "expirationDate": "2019-08-24T14:15:22+03:00"
}

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

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

path Parameters
orderId
required
string

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

header Parameters
Authorization
required

Responses

Request samples

<?php

$orderId = 'testOrder';

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

?>

Response samples

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

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

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

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

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

query Parameters
receiptType
string
Enum: "sell" "refund"

Тип чека:
• sell – чек прихода
• refund – чек возврата

header Parameters
Authorization
required

Responses

Response Schema: application/json
Array
One of
receiptNumber
string <= 99 characters ^[A-Za-z0-9_-]+$

Уникальный номер чека

receiptType
string
Enum: "SELL" "REFUND"

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

status
string
Enum: "NEW" "IN_PROGRESS" "DONE" "FAILED" "AWAITING"

Статус регистрации чека. Возможные значения:
• NEW – создан черновик чека
• IN_PROGRESS – чек в процессе регистрации в ОФД
• DONE – чек успешно зарегистрирован в ОФД
• FAILED – регистрация чека в ОФД завершилась ошибкой
• AWAITING – технический статус перед отправкой чека на регистрацию в ОФД

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

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

total
number

Итоговая сумма чека в рублях

ofdUrl
string

Ссылка на чек
Передается в ответе только для чеков в статусе DONE и при условии, что была получена от ОФД при регистрации чека. Список ОФД, которые поддерживают передачу ссылки на чек, необходимо уточнять у поставщика онлайн-кассы

object

Данные о покупателе

Array of objects (ФФД 1.05) [ 1 .. 100 ] items unique [ items ]

Позиции чека

Array of objects (платежи) non-empty unique [ items ]

Данные об оплате

Request samples

<?php

$orderId = 'testOrder';

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

print_r($response);

?>

Response samples

Content type
application/json
Example
[
  • {
    • "receiptNumber": "3000827351832",
    • "receiptType": "REFUND",
    • "status": "DONE",
    • "orderNumber": "testOrder",
    • "total": 1200,
    • "customer": {
      • "email": "customer@test.ru",
      • "name": "Иванов Иван Иванович"
      },
    • "items": [
      • {
        • "name": "Шоколадный торт",
        • "price": 1200,
        • "quantity": 1,
        • "amount": 1200,
        • "paymentObject": "COMMODITY",
        • "paymentMode": "FULL_PAYMENT",
        • "measurementUnit": "шт",
        • "nomenclatureCode": "00 00 00 01 00 21 FA 41 00 23 05 41 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 12 00 AB 00",
        • "vatType": "VAT20",
        • "agentType": "ANOTHER",
        • "supplierInfo": {
          • "phone": "+79991234567",
          • "name": "ООО «Ромашка»",
          • "inn": "956839506500"
          }
        }
      ],
    • "payments": [
      • {
        • "type": "PREPAID",
        • "amount": 1200
        }
      ]
    }
]

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

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

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

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

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

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

header Parameters
Authorization
required

Responses

Response Schema: application/json
One of
receiptNumber
string <= 99 characters ^[A-Za-z0-9_-]+$

Уникальный номер чека

receiptType
string
Enum: "SELL" "REFUND"

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

status
string
Enum: "NEW" "IN_PROGRESS" "DONE" "FAILED" "AWAITING"

Статус регистрации чека. Возможные значения:
• NEW – создан черновик чека
• IN_PROGRESS – чек в процессе регистрации в ОФД
• DONE – чек успешно зарегистрирован в ОФД
• FAILED – регистрация чека в ОФД завершилась ошибкой
• AWAITING – технический статус перед отправкой чека на регистрацию в ОФД

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

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

total
number

Итоговая сумма чека в рублях

ofdUrl
string

Ссылка на чек
Передается в ответе только для чеков в статусе DONE и при условии, что была получена от ОФД при регистрации чека. Список ОФД, которые поддерживают передачу ссылки на чек, необходимо уточнять у поставщика онлайн-кассы

object

Данные о покупателе

Array of objects (ФФД 1.05) [ 1 .. 100 ] items unique [ items ]

Позиции чека

Array of objects (платежи) non-empty unique [ items ]

Данные об оплате

Request samples

<?php

$orderId = 'testOrder';
$refundId = 'testRefund';

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

print_r($response);

?>

Response samples

Content type
application/json
Example
{
  • "receiptNumber": "3000827351831",
  • "receiptType": "REFUND",
  • "status": "DONE",
  • "orderNumber": "testOrder",
  • "total": 1200,
  • "customer": {
    • "email": "customer@test.ru",
    • "name": "Иванов Иван Иванович"
    },
  • "items": [
    • {
      • "name": "Шоколадный торт",
      • "price": 1200,
      • "quantity": 1,
      • "amount": 1200,
      • "paymentObject": "COMMODITY",
      • "paymentMode": "FULL_PAYMENT",
      • "measurementUnit": "шт",
      • "nomenclatureCode": "00 00 00 01 00 21 FA 41 00 23 05 41 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 12 00 AB 00",
      • "vatType": "VAT20",
      • "agentType": "ANOTHER",
      • "supplierInfo": {
        • "phone": "+79991234567",
        • "name": "ООО «Ромашка»",
        • "inn": "956839506500"
        }
      }
    ],
  • "payments": [
    • {
      • "type": "PREPAID",
      • "amount": 1200
      }
    ]
}

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

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

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

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

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

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

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

Для проверки подлинности уведомления к данным добавляется подпись в заголовке x-api-signature-sha256, полученная на основе общего секретного ключа и контрольной строки (amount|publicId|order|transaction.status.value|transaction.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": {
    • "id": 120059,
    • "orderId": "testOrder",
    • "status": {
      • "value": "SUCCESS",
      • "date": "2019-07-11T17:45:13+03:00"
      },
    • "paymentMethod": "acquiring",
    • "paymentParams": {
      • "rrn": 935014591810,
      • "authCode": "259AA"
      },
    • "amount": 12500.5,
    • "comment": "Покупка шоколадного торта",
    • "extra": {
      • "apiClient": "Payform Software",
      • "apiClientVersion": "1.0.0"
      }
    }
}

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

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

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

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

Responses

Response Schema: application/json
callbackUrl
required
string

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

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)

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

Выписка

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

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

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

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

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

query Parameters
from
required
string YYYY-MM-DD ТHH24:MM:SS±HH:MM

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

to
required
string YYYY-MM-DD ТHH24:MM:SS±HH:MM

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

operationTypes
string
Enum: "Payment" "Refund"

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

qrId
string

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

header Parameters
Authorization

Responses

Response Schema: application/json
object

Операции СБП

object

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

Response samples

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

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

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

query Parameters
from
required
string YYYY-MM-DD ТHH24:MM:SS±HH:MM

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

to
required
string YYYY-MM-DD ТHH24:MM:SS±HH:MM

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

operationTypes
string
Enum: "Payment" "Refund"

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

qrId
string

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

header Parameters
Authorization

Responses

Response Schema: application/json
object

Операции СБП

object

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

Response samples

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

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

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

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

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

21.10.2021

  • Добавлен параметр expirationDate - ответчающий за срок жизни заказа

29.10.2021

  • Добавлены методы для отмены заказа и получения его статуса.

30.12.2021

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

18.01.2022

  • Для фискализации в чек прихода добавлены новые параметры для агентских операций: agentType, supplierInfo.

05.03.2022

  • Расширен API для оформления возврата для возможности пробить чек. В т.ч. в POST-метод добавлен новый объект receipt для передачи данных чека
  • Добавлен API для получения массива чеков по заказу
  • Добавлен API для получения чека возврата по заказу и идентификатору возврата
  • Реализовано переключение через кнопки "с чеком/без чека" для API, где возможен один из вариантов
  • Добавлен перевод документации на английский язык

25.03.2022

  • В модель чека добавлен параметр paymentMode для передачи способа расчёта (100% предоплата, полный расчет)

15.04.2022

  • В документацию добавлен партнер "БИФИТ", приведена инструкция по подключению онлайн-кассы сервиса БИФИТ
  • Скорректированы примеры запроса на сохранение чека (удалены параметры для агентских операций)
  • Дополнено правило заполнения номеклатурного кода для партнера "БИФИТ"
  • Небольшие правки по тексту

17.05.2022

  • Добавлен метод открытия платежной формы через POST-метод

30.05.2022

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

27.07.2022

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

29.07.2022

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

26.08.2022

  • Добавлен ФФД 1.2 для сервиса "АТОЛ Онлайн"

30.09.2022

  • Реализована поддержка авансовых чеков и чеков частичной предоплаты

11.10.2022

  • Добавлены SDK с описанием в методах

02.11.2022

  • Добавлены рекомендации по работе с QRVariable и передачей дополнительных параметров apiClient и apiClientVersion

16.12.2022

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

29.03.2023

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