Raiffeisenbank e-commerce API (1.0)
Download OpenAPI specification:Download
Свои предложения и идеи о документации можно оставить в репозитории по адресу: https://github.com/Raiffeisen-DGTL/ecom-API/blob/master/ecom.yaml
Для подключения перейдите на сайт.
По остальным вопросам работы с API необходимо обращаться в Службу Поддержки Raiffeisenbank:
- email: ecom@raiffeisen.ru
Подготовительные мероприятия
Чтобы принимать платежи:
- подайте заявку на подключение эквайринга
- заключите договор с Райффайзенбанком
- выберите способ интеграции и реализуйте его
- успешно проведите тестовые платежи.
Способы интеграции платежной страницы
Для интеграции платежной страницы используйте:
- готовую библиотеку, позволяющую открыть popup для ввода данных платежа и передать сложную структуру данных
- перенаправление клиента на платежную страницу Райффайзенбанка
Демонстрация: https://e-commerce.raiffeisen.ru/pay/demo.html
Пользователь совершает следующие действия в процессе платежа:
- Выбирает товары/услуги в корзину магазина и нажимает кнопку “Оплатить”.
- Партнер открывает платежную форму.
- Клиент вводит реквизиты на платежной форме и подтверждает платеж.
Схема выполнения платежа представлена ниже:
По закону от 22.05.2003 № 54–ФЗ "О применении контрольно-кассовой техники при осуществлении расчетов в Российской Федерации" при оплате товаров, работ или услуг необходимо формировать фискальный чек и отправлять его в налоговую с помощью кассы.
Клиенты Райффайзенбанка, подключившие интернет-эквайринг, также могут воспользоваться услугой фискализации чеков через онлайн-кассу. Пошаговые инструкции приведены ниже.
- Подключите онлайн-кассу в сервисе OFD.ru
- Зарегистрируйте кассу в ФНС через сервис Ferma по инструкции
- Составьте заявку на подключение
В заявке необходимо указать данные:
- Поставщик кассового оборудования – OFD.ru
- Идентификаторы мерчантов (publicId)
- Применяемая система налогообложения
- E-mail (для получения чека, если E-mail не указан покупателем)
- Логин, пароль и идентификатор группы ККТ от OFD.ru (см. ниже)
Для получения данных по подключенной кассе в OFD.ru перейдите в раздел Ferma в личном кабинете клиента и пролистайте до виджета "Реквизиты доступа". Скопируйте логин, пароль и идентификатор группы ККТ для подключения.
- Отправьте заявку в банк одним из способов:
- По E-mail ecom@raiffeisen.ru. Пример заявки доступнен при нажатии на E-mail.
- Через менеджера банка. Для этого отправьте ему безопасным способом необходимые для подключения данные.
- Убедитесь, что при вызове платежной формы передаются данные, необходимые для формирования чека (см. объект receipt в JS-библиотеке)
После активации услуги чеки будут автоматически регистрироваться через выбранную кассу. Помимо автоматической фискализации чеков также доступна фискализация через API банка.
- Зарегистрируйтесь в сервисе "АТОЛ Онлайн" и подключите онлайн-кассу
- Заключите договор с оператором фискальных данных
- Составьте заявку на подключение
В заявке необходимо указать данные:
- Поставщик кассового оборудования – "АТОЛ Онлайн"
- Идентификаторы мерчантов (publicId)
- Применяемая система налогообложения
- E-mail (для получения чека, если E-mail не указан покупателем)
- Логин, пароль и идентификатор группы ККТ от "АТОЛ Онлайн" (см. ниже)
Чтобы получить логин, пароль и идентификатор, зайдите в личный кабинет "АТОЛ Онлайн". Выберите раздел "Мои компании", нажмите кнопку "Настройки интегратора". Скачается XML-файл с настройками, найдите в файле элемент access, в нём будут все три параметра: login, password, group_code. Если возникли трудности, обратитесь в техподдержку "АТОЛ Онлайн".
- Отправьте заявку в банк одним из способов:
- По E-mail ecom@raiffeisen.ru. Пример заявки доступнен при нажатии на E-mail.
- Через менеджера банка. Для этого отправьте ему безопасным способом необходимые для подключения данные.
- Убедитесь, что при вызове платежной формы передаются данные, необходимые для формирования чека (см. объект receipt в JS-библиотеке)
После активации услуги чеки будут автоматически регистрироваться через выбранную кассу. Помимо автоматической фискализации чеков также доступна фискализация через API банка.
- Зарегистрируйтесь в сервисе "Чек-Онлайн" и подключите онлайн-кассу
- Заключите договор с оператором фискальных данных
- Составьте заявку на подключение
В заявке необходимо указать данные:
- Поставщик кассового оборудования – "Чек-Онлайн"
- Идентификаторы мерчантов (publicId)
- Применяемая система налогообложения
- E-mail (для получения чека, если E-mail не указан покупателем)
- Логин, пароль и идентификатор группы ККТ от "Чек-Онлайн" (см. ниже)
Чтобы получить логин и пароль, зайдите в личный кабинет клиента. Откройте раздел "Предприятия", найдите в списке нужную компанию и нажмите на иконку в поле "Авторизация". Откроется раздел, в котором можно выбрать существующие логин и пароль или сгенерировать новые. Для получения идентификатора группы ККТ вернитесь в раздел "Предприятия" и выберите нужную компанию из списка. В открывшемся профиле предприятия скопируйте API Group ID.
- Отправьте заявку в банк одним из способов:
- По E-mail ecom@raiffeisen.ru. Пример заявки доступнен при нажатии на E-mail.
- Через менеджера банка. Для этого отправьте ему безопасным способом необходимые для подключения данные.
- Убедитесь, что при вызове платежной формы передаются данные, необходимые для формирования чека (см. объект receipt в JS-библиотеке)
После активации услуги чеки будут автоматически регистрироваться через выбранную кассу. Помимо автоматической фискализации чеков также доступна фискализация через API банка.
- Заключите договор с БИФИТ на аренду ККТ
- Оплатите аренду ККТ и ФН. БИФИТ предоставит бесплатное подключение к ОФД Яндекс. При необходимости можно подключиться к другому ОФД. Для этого в ЛК найдите № ККТ и № ФН и выполните регистрацию в ОФД на свой выбор
- Составьте заявку на подключение, в ней укажите данные:
– Поставщик кассового оборудования – БИФИТ
– Идентификаторы мерчантов (publicId)
– Применяемая система налогообложения
– E-mail (для получения чека, если E-mail не указан покупателем)
– Токен коннектора и идентификатор ККТ в системе БИФИТ (см. ниже)
Для получения данных по подключенной кассе в БИФИТ перейдите в личный кабинет, откройте пункт меню «Бифит Онлайн» и перейдите в раздел «Коннекторы ККТ». Создайте токен коннектора и привяжите к нему кассу. Скопируйте токен коннектора и заводской номер ККТ (идентификатор ККТ). - Отправьте заявку в банк одним из способов:
– По E-mail на п/я ecom@raiffeisen.ru
– Через менеджера банка. Для этого отправьте ему безопасным способом необходимые для подключения данные. - Убедитесь, что при вызове платежной формы передаются данные, необходимые для формирования чека (см. объект receipt в JS-библиотеке)
После активации услуги чеки будут автоматически регистрироваться через выбранную кассу. Помимо автоматической фискализации чеков также доступна фискализация через API банка.
Bзаимодействие осуществляется по протоколу HTTP с использованием методов GET/POST (в описании каждого запроса явно указан требуемый метод и адрес).
POST-запросы используют JSON-аргументы, GET-запросы работают со строками запросов.
API всегда возвращает ответ в формате JSON, независимо от типа запроса.
Ответ любого метода содержит код сообщения (code). Если в процессе обработки любого запроса произойдет логическая ошибка, API вернет дополнительно описание ошибки (message).
Для авторизация запросов необходимы:
- publicId - идентификатор, который используется для открытия платежной формы и не является конфиденциальным.
- secretKey - секретный ключ, который используется для межсервисного взаимодействия.
Продовый хост: https://e-commerce.raiffeisen.ru
Тестовый хост: https://test.ecom.raiffeisen.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 от имени покупателя по адресу: https://pay.raif.ru/pay/rfuture/
Указанный адрес можно открыть в браузере любого устройства, где есть камера. Никакого дополнительного софта/плагинов устанавливать не нужно. Далее нажать на значок СБП (при необходимости разрешить браузеру доступ к камере) и поднести к ней изображение QR-кода. Если камера не открылась, проверьте, что в адресе указан протокол https.
Использование библиотеки позволяет открывать форму в pop-up окне, что обеспечивает бесшовный сценарий для клиента. Также возможно выполнить кастомизацию интерфейса платежной формы и передать дополнительные поля.
Использование JS-библиотеки описано в репозитории https://github.com/Raiffeisen-DGTL/ecom-sdk-javascript
Вы можете настроить название, логотип и цвет кнопок на форме в нашем конфигураторе: https://pay.raif.ru/pay/configurator/
Там же можно получить код для встраивания его в JS-библиотеку.
Ниже указан пример запроса на оплату:
| publicId required | string Идентификатор магазина |
| orderId | string <= 40 characters ^[A-z0-9-_.]+$ Order ID |
| amount required | number Сумма платежа в рублях. Минимальная сумма для ооплаты картой 10 рублей. Для копеек доступно два знака после разделителя. |
| comment | string <= 140 characters Комментарий |
| successUrl | string URL ресурса, куда будет перенаправлен клиент в случае успешного платежа |
| failUrl | string URL ресурса, куда будет перенаправлен клиент в случае неуспешного платежа |
| extra | object Структура с дополнительными параметрами от магазина |
| 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 |
object Данные чека. Объект должен быть передан, если подключена фискализация чеков. При отсутствии объекта receipt чек не будет создан |
{- "publicId": "000001680200002-80200002",
- "orderId": "orderTest",
- "amount": 1200,
- "comment": "Покупка шоколадного торта",
- "failUrl": "string",
- "extra": {
- "additionalInfo": "Sweet Cake"
}, - "paymentMethod": "ONLY_SBP",
- "locale": "ru",
- "expirationDate": "2021-10-21T14:17:00.000+03:00",
- "receipt": {
- "receiptNumber": "3000827351831",
- "customer": {
- "email": "customer@test.ru",
- "name": "Иванов Иван Иванович"
}, - "items": [
- {
- "name": "Шоколадный торт",
- "price": 1200,
- "quantity": 1,
- "amount": 1200,
- "paymentObject": "COMMODITY",
- "paymentMode": "FULL_PREPAYMENT",
- "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": "1234567890"
}
}
]
}
}Простой способ для интеграции. Клиента необходимо перенаправить на платежную форму, передав параметры заказа. Кастомизация интерфейса формы или передача дополнительных полей в данном варианте интеграции недоступны.
Открытие платежной формы
При редиректе клиента на полученный URL откроется форма для оплаты
query Parameters
| publicId required | string Идентификатор магазина |
| amount required | string Сумма платежа в рублях. Минимальный платеж по карте 10 рублей. Для копеек доступно два знака после точки. |
| orderId | string <= 40 characters ^[A-z0-9-_.]+$ Идентификатор заказа в магазине |
| comment | string <URL encoded> <= 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 |
Responses
Создание заказа с открытием формы
Метод позволяет создать заказ с открытием формы
header Parameters
| Content-Type required | string application/json |
Request Body schema: application/json
| publicId required | string Идентификатор магазина |
| orderId | string <= 40 characters ^[A-z0-9-_.]+$ Order ID |
| amount required | number Сумма платежа в рублях. Минимальная сумма для ооплаты картой 10 рублей. Для копеек доступно два знака после разделителя. |
| comment | string <= 140 characters Комментарий |
| successUrl | string URL ресурса, куда будет перенаправлен клиент в случае успешного платежа |
| failUrl | string URL ресурса, куда будет перенаправлен клиент в случае неуспешного платежа |
| extra | object Структура с дополнительными параметрами от магазина |
| 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 |
object Данные чека. Объект должен быть передан, если подключена фискализация чеков. При отсутствии объекта receipt чек не будет создан |
Responses
Request samples
- Payload
{- "publicId": "000001680200002-80200002",
- "orderId": "orderTest",
- "amount": 1200,
- "comment": "Покупка шоколадного торта",
- "failUrl": "string",
- "extra": {
- "additionalInfo": "Sweet Cake"
}, - "paymentMethod": "ONLY_SBP",
- "locale": "ru",
- "expirationDate": "2021-10-21T14:17:00.000+03:00",
- "receipt": {
- "receiptNumber": "3000827351831",
- "customer": {
- "email": "customer@test.ru",
- "name": "Иванов Иван Иванович"
}, - "items": [
- {
- "name": "Шоколадный торт",
- "price": 1200,
- "quantity": 1,
- "amount": 1200,
- "paymentObject": "COMMODITY",
- "paymentMode": "FULL_PREPAYMENT",
- "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": "1234567890"
}
}
]
}
}Для реализации взаимодействия с партнёром Райффайзенбанк предоставляет API для:
- открытия платежной формы с ипользованием HTTP запросов;
- получения информации о статусе заказа.
Получение информации о статусе транзакции
Метод позволяет получить статус транзакции. Необходимо проверять сумму, так как у клиентов есть возможность ее изменить.
path Parameters
| orderId required | string <= 40 characters A-z0-9-_. Идентификатор заказа в магазине |
header Parameters
| Authorization required | string |
Responses
Response samples
- 200
{- "code": "SUCCESS",
- "transaction": {
- "id": 120059,
- "orderId": "testOrder",
- "status": {
- "value": "SUCCESS",
- "date": "2019-07-11T17:45:13+03:00"
}, - "paymentMethod": "acquiring",
- "paymentParams": {
- "rrn": 935014591810,
- "authCode": 25984
}, - "amount": 12500.5,
- "comment": "Покупка шоколадного торта",
- "extra": {
- "additionalInfo": "Sweet Cake"
}
}
}Оформление возврата по платежу
Метод позволяет выполнить отмену/возврат по платежу, как полную, так и частичную.
В случае с СБП выполняется только возврат.
Для мерчантов с подключенной фискализацией метод также позволяет пробить фискальный чек по возврату. Для этого необходимо в теле запроса передать данные чека в объекте receipt.
В таком случае чек возврата будет пробит автоматически. Если объект не передан, то возврат будет проведен без чека.
path Parameters
| orderId required | string <= 40 characters A-z0-9-_. Идентификатор заказа в магазине |
| refundId required | string <= 40 characters A-z0-9-_. Уникальный идентификатор запроса на возврат в системе партнера |
header Parameters
| Content-Type required | string application/json |
| Authorization required | string |
Request Body schema: application/json
| amount required | number Сумма возврата в рублях |
Responses
Request samples
- Payload
{- "amount": 150
}Response samples
- 200
- 400
{- "code": "SUCCESS",
- "amount": 150,
- "refundStatus": "IN_PROGRESS"
}Статус возврата
Метод позволяет получить статус по отмене/возврату.
path Parameters
| orderId required | string <= 40 characters A-z0-9-_. Идентификатор заказа в магазине |
| refundId required | string <= 40 characters A-z0-9-_. Уникальный идентификатор запроса на возврат в системе партнера |
header Parameters
| Authorization required | string |
Responses
Response samples
- 200
{- "code": "SUCCESS",
- "amount": 150,
- "refundStatus": "COMPLETED"
}Получение информации о заказе
Метод позволяет получить данные о заказе
path Parameters
| orderId required | string Идентификатор заказа в магазине |
header Parameters
| Authorization required | string |
Responses
Response samples
- 200
- 404
{- "amount": 12500.5,
- "comment": "Покупка шоколадного торт",
- "extra": {
- "additionalInfo": "sweet cake"
}, - "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 | string |
Responses
Response samples
- 400
- 404
{- "code": "ORDER_HAS_FINAL_STATUS",
- "message": "Заказ с идентификатором test123 имеет статус PAID"
}Получение списка чеков
Метод позволяет получить по заказу список чеков, которые успешно зарегистрированы в ОФД и имеют статус DONE. По умолчанию возвращаются как чеки прихода, так и чеки возврата. Чтобы получить чеки определенного типа, необходимо в строке запроса передать дополнительный параметр receiptType.
Если ни один чек не найден, в ответ вернется 200 OK и пустой массив.
path Parameters
| orderId required |