Download OpenAPI specification:Download
Свои предложения и идеи о документации можно оставить в репозитории по адресу: https://github.com/Raiffeisen-DGTL/ecom-API/blob/master/ecom.yaml
Для подключения перейдите на сайт.
По остальным вопросам работы с API необходимо обращаться в Службу Поддержки Raiffeisenbank:
Чтобы принимать платежи:
Для интеграции платежной страницы используйте:
Демонстрация: https://e-commerce.raiffeisen.ru/pay/demo.html
Пользователь совершает следующие действия в процессе платежа:
Схема выполнения платежа представлена ниже:
По закону от 22.05.2003 № 54–ФЗ "О применении контрольно-кассовой техники при осуществлении расчетов в Российской Федерации" при оплате товаров, работ или услуг необходимо формировать фискальный чек и отправлять его в налоговую с помощью кассы.
Клиенты Райффайзенбанка, подключившие интернет-эквайринг, также могут воспользоваться услугой фискализации чеков через онлайн-кассу. Пошаговые инструкции приведены ниже.
В заявке необходимо указать данные:
Для получения данных по подключенной кассе в OFD.ru перейдите в раздел Ferma в личном кабинете клиента и пролистайте до виджета "Реквизиты доступа". Скопируйте логин, пароль и идентификатор группы ККТ для подключения.
После активации услуги чеки будут автоматически регистрироваться через выбранную кассу. Помимо автоматической фискализации чеков также доступна фискализация через API банка.
В заявке необходимо указать данные:
Чтобы получить логин, пароль и идентификатор, зайдите в личный кабинет "АТОЛ Онлайн". Выберите раздел "Мои компании", нажмите кнопку "Настройки интегратора". Скачается XML-файл с настройками, найдите в файле элемент access, в нём будут все три параметра: login, password, group_code. Если возникли трудности, обратитесь в техподдержку "АТОЛ Онлайн".
После активации услуги чеки будут автоматически регистрироваться через выбранную кассу. Помимо автоматической фискализации чеков также доступна фискализация через API банка.
В заявке необходимо указать данные:
Чтобы получить логин и пароль, зайдите в личный кабинет клиента. Откройте раздел "Предприятия", найдите в списке нужную компанию и нажмите на иконку в поле "Авторизация". Откроется раздел, в котором можно выбрать существующие логин и пароль или сгенерировать новые. Для получения идентификатора группы ККТ вернитесь в раздел "Предприятия" и выберите нужную компанию из списка. В открывшемся профиле предприятия скопируйте API Group ID.
После активации услуги чеки будут автоматически регистрироваться через выбранную кассу. Помимо автоматической фискализации чеков также доступна фискализация через API банка.
После активации услуги чеки будут автоматически регистрироваться через выбранную кассу. Помимо автоматической фискализации чеков также доступна фискализация через API банка.
Bзаимодействие осуществляется по протоколу HTTP с использованием методов GET/POST (в описании каждого запроса явно указан требуемый метод и адрес).
POST-запросы используют JSON-аргументы, GET-запросы работают со строками запросов.
API всегда возвращает ответ в формате JSON, независимо от типа запроса.
Ответ любого метода содержит код сообщения (code). Если в процессе обработки любого запроса произойдет логическая ошибка, API вернет дополнительно описание ошибки (message).
Для авторизация запросов необходимы:
Продовый хост: 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 рублей. Карты для тестовой среды:
Для полного цикла тестирования оплаты Райффайзенбанк предоставляет возможность использования демо-приложения для сканирования 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 откроется форма для оплаты
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 |
Метод позволяет создать заказ с открытием формы
Content-Type required | string 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 чек не будет создан |
{- "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 для:
Метод позволяет получить статус транзакции. Необходимо проверять сумму, так как у клиентов есть возможность ее изменить.
orderId required | string <= 40 characters A-z0-9-_. Идентификатор заказа в магазине |
Authorization required | string |
{- "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.
В таком случае чек возврата будет пробит автоматически. Если объект не передан, то возврат будет проведен без чека.
orderId required | string <= 40 characters A-z0-9-_. Идентификатор заказа в магазине |
refundId required | string <= 40 characters A-z0-9-_. Уникальный идентификатор запроса на возврат в системе партнера |
Content-Type required | string application/json |
Authorization required | string |
amount required | number Сумма возврата в рублях |
{- "amount": 150
}
{- "code": "SUCCESS",
- "amount": 150,
- "refundStatus": "IN_PROGRESS"
}
Метод позволяет получить статус по отмене/возврату.
orderId required | string <= 40 characters A-z0-9-_. Идентификатор заказа в магазине |
refundId required | string <= 40 characters A-z0-9-_. Уникальный идентификатор запроса на возврат в системе партнера |
Authorization required | string |
{- "code": "SUCCESS",
- "amount": 150,
- "refundStatus": "COMPLETED"
}
Метод позволяет получить данные о заказе
orderId required | string Идентификатор заказа в магазине |
Authorization required | string |
{- "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"
}
Данный метод позволяет отменить заказ, если он не был оплачен. После отмены страница оплаты будет недоступна.
orderId required | string Идентификатор заказа в магазине |
Authorization required | string |
{- "code": "ORDER_HAS_FINAL_STATUS",
- "message": "Заказ с идентификатором test123 имеет статус PAID"
}
Метод позволяет получить по заказу список чеков, которые успешно зарегистрированы в ОФД и имеют статус DONE. По умолчанию возвращаются как чеки прихода, так и чеки возврата. Чтобы получить чеки определенного типа, необходимо в строке запроса передать дополнительный параметр receiptType.
Если ни один чек не найден, в ответ вернется 200 OK и пустой массив.
orderId required |