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://pay.raif.ru/pay/demo.html
Пользователь совершает следующие действия в процессе платежа:
- Выбирает товары/услуги в корзину магазина и нажимает кнопку “Оплатить”.
- Партнер открывает платежную форму.
- Клиент вводит реквизиты на платежной форме и подтверждает платеж.
Схема выполнения платежа представлена ниже:
По закону от 22.05.2003 № 54–ФЗ "О применении контрольно-кассовой техники при осуществлении расчетов в Российской Федерации" при оплате товаров, работ или услуг необходимо формировать фискальный чек и отправлять его в налоговую с помощью кассы.
Клиенты Райффайзенбанка, подключившие интернет-эквайринг, также могут воспользоваться услугой фискализации чеков через онлайн-кассу. Пошаговые инструкции приведены ниже.
- Зарегистрируйтесь в сервисе "АТОЛ Онлайн" и подключите онлайн-кассу
- Заключите договор с оператором фискальных данных
- Зайдите в личный кабинет "АТОЛ Онлайн", чтобы получить логин, пароль и идентификатор. Выберите раздел "Мои компании", нажмите кнопку "Настройки интегратора". Скачается XML-файл с настройками, найдите в файле элемент access, в нём будут все три параметра: login, password, group_code. Если возникли трудности, обратитесь в техподдержку "АТОЛ Онлайн".
- Подключите фискализацию в Личном кабинете Raif Pay или RBO
В Личном кабинете Raif Pay: Настройки → Фискализация чеков → Подключить
В RBO: Прием платежей → Настройки → Фискализация чеков → Подключить - Убедитесь, что при вызове платежной формы передаются данные, необходимые для формирования чека (см. объект receipt в методе создания заказа при открытии формы)
После этого чеки будут автоматически регистрироваться через выбранную кассу. Помимо автоматической фискализации чеков также доступна фискализация через API банка.
- Подключите онлайн-кассу в сервисе OFD.ru
- Зарегистрируйте кассу в ФНС через сервис Ferma по инструкции
Для получения данных по подключенной кассе в OFD.ru перейдите в раздел Ferma в личном кабинете клиента и пролистайте до виджета "Реквизиты доступа". Скопируйте логин, пароль и идентификатор группы ККТ для подключения. Эти данные понадобятся на следующем шаге.
- Подключите фискализацию в Личном кабинете Raif Pay или RBO
В Личном кабинете Raif Pay: Настройки → Фискализация чеков → Подключить
В RBO: Прием платежей → Настройки → Фискализация чеков → Подключить - Убедитесь, что при вызове платежной формы передаются данные, необходимые для формирования чека (см. объект receipt в методе создания заказа при открытии формы)
После этого чеки будут автоматически регистрироваться через выбранную кассу. Помимо автоматической фискализации чеков также доступна фискализация через API банка.
- Зарегистрируйтесь в сервисе "Чек-Онлайн" и подключите онлайн-кассу
- Заключите договор с оператором фискальных данных
- Зайдите в личный кабинет клиента, чтобы получить логин и пароль. Откройте раздел "Предприятия", найдите в списке нужную компанию и нажмите на иконку в поле "Авторизация". Откроется раздел, в котором можно выбрать существующие логин и пароль или сгенерировать новые. Для получения идентификатора группы ККТ вернитесь в раздел "Предприятия" и выберите нужную компанию из списка. В открывшемся профиле предприятия скопируйте API Group ID. Эти данные понадобятся на следующем шаге.
- Подключите фискализацию в Личном кабинете Raif Pay или RBO
В Личном кабинете Raif Pay: Настройки → Фискализация чеков → Подключить
В RBO: Прием платежей → Настройки → Фискализация чеков → Подключить - Убедитесь, что при вызове платежной формы передаются данные, необходимые для формирования чека (см. объект receipt в методе создания заказа при открытии формы)
После этого чеки будут автоматически регистрироваться через выбранную кассу. Помимо автоматической фискализации чеков также доступна фискализация через API банка.
- Заключите договор с БИФИТ на аренду ККТ
- Оплатите аренду ККТ и ФН. БИФИТ предоставит бесплатное подключение к ОФД Яндекс. При необходимости можно подключиться к другому ОФД. Для этого в ЛК найдите № ККТ и № ФН и выполните регистрацию в ОФД на свой выбор
- Перейдите в личный кабинет БИФИТ для получения данных по подключенной кассе. Откройте пункт меню «Бифит Онлайн» и перейдите в раздел «Коннекторы ККТ». Создайте токен коннектора и привяжите к нему кассу. Скопируйте токен коннектора и заводской номер ККТ (идентификатор ККТ)
- Подключите фискализацию в Личном кабинете Raif Pay или RBO
В Личном кабинете Raif Pay: Настройки → Фискализация чеков → Подключить
В RBO: Прием платежей → Настройки → Фискализация чеков → Подключить - Убедитесь, что при вызове платежной формы передаются данные, необходимые для формирования чека (см. объект receipt в методе создания заказа при открытии формы)
После этого чеки будут автоматически регистрироваться через выбранную кассу. Помимо автоматической фискализации чеков также доступна фискализация через API банка.
- Оставьте заявку на облачную онлайн-кассу по ссылке. В заявке в поле Продукт укажите "Облачная касса".
Поля для ИНН, номера телефона, имени и E-mail обязательны к заполнению. В поле "Комментарий" при необходимости можно указать дополнительную информацию. Например, "Позвонить по заявке завтра после 14:00" - После подключения облачной кассы зайдите в личный кабинет LIFE PAY → Настройки → Разработчикам. В этом разделе скопируйте API KEY
- Подключите фискализацию в Личном кабинете Raif Pay или RBO
В Личном кабинете Raif Pay: Настройки → Фискализация чеков → Подключить
В RBO: Прием платежей → Настройки → Фискализация чеков → Подключить
В поле Логин укажите номер телефона в формате 7xxxxxxxxxx, а в поле Пароль - API KEY, скопированный ранее - Убедитесь, что при вызове платежной формы передаются данные, необходимые для формирования чека (см. объект receipt в методе создания заказа при открытии формы)
После этого чеки будут автоматически регистрироваться через выбранную кассу. Помимо автоматической фискализации чеков также доступна фискализация через API банка.
- Оставьте заявку на облачную онлайн-кассу на сайте Эвотор
- После подключения облачной кассы зайдите в личный кабинет Эвотор и получите приветственное письмо на E-mail. В личном кабинете и в письме содержатся логин, пароль и идентификатор группы касс. Скопируйте эти данные.
- Подключите фискализацию в Личном кабинете Raif Pay или RBO
В Личном кабинете Raif Pay: Настройки → Фискализация чеков → Подключить
В RBO: Прием платежей → Настройки → Фискализация чеков → Подключить - Убедитесь, что при вызове платежной формы передаются данные, необходимые для формирования чека (см. объект receipt в методе создания заказа при открытии формы)
После этого чеки будут автоматически регистрироваться через выбранную кассу. Помимо автоматической фискализации чеков также доступна фискализация через API банка.
Bзаимодействие осуществляется по протоколу HTTP с использованием методов GET/POST (в описании каждого запроса явно указан требуемый метод и адрес).
POST-запросы используют JSON-аргументы, GET-запросы работают со строками запросов.
API всегда возвращает ответ в формате 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.
Использование JS SDK позволяет открывать форму с фронтовой части в pop-up окне, либо редиректить пользователя на страницу Банка, что обеспечивает бесшовный сценарий для клиента.
Дополнительно возможно кастомизировать интерфейс платежной формы и передавать дополнительные поля.
Вы можете настроить название, логотип и цвет кнопок на форме в нашем конфигураторе: Конфигуратор
Там же можно получить код для встраивания его в JS-библиотеку.
Доступные SDK:
При использовании остальных 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
| 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 ресурса, куда будет перенаправлен клиент в случае неуспешного платежа |
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 |
| successSbpUrl | string <uri> Ссылка для автоматического возврата плательщика из приложения банка в приложение или на сайт магазина. Ссылка должна содержать https:// для web страниц или уникальную схему для мобильного приложения. |
| paymentDetails | string <= 140 characters Назначение платежа для платежей по СБП |
Responses
Request samples
- Payload
- JS
- Node
{- "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",
- "paymentDetails": "string"
}Response samples
- 415
{- "timestamp": "2023-02-15T06:36:32.418+00:00",
- "status": 415,
- "error": "Unsupported Media Type",
- "path": "string"
}Для реализации взаимодействия с партнёром Райффайзенбанк предоставляет API для:
- открытия платежной формы с ипользованием HTTP запросов;
- получения информации о статусе заказа.
Получение информации о статусе транзакции
Метод позволяет получить статус транзакции. Необходимо проверять сумму, так как у клиентов есть возможность ее изменить.
path Parameters
| orderId required | string <= 40 characters A-z0-9-_. Идентификатор заказа в магазине |
header Parameters
| Authorization required | string |
Responses
Response Schema: application/json
| code | string Enum: "SUCCESS" "ERROR" Код состояния http запроса |
any (transaction) Данные по операции |
Request samples
- PHP
- Node
- Java
<?php
$orderId = 'testOrder';
/** @var \Raiffeisen\Ecom\Client $client */
$response = $client->getOrderTransaction($orderId);
print_r($response);
?>
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": "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 | string |
Request Body schema: application/json
| amount required | number Сумма возврата в рублях |
| paymentDetails | string <= 140 characters Назначение платежа для СБП. Не может быть пустым или содержать только пробелы. Может сождержать: |
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
- Payload
- PHP
- Node
- Java
{- "amount": 1200,
- "paymentDetails": "string"
}Response samples
- 200
- 400
- 415
{- "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 | string |
Responses
Response Schema: application/json
| code | string Enum: "SUCCESS" "ERROR" Код состояния http запроса |
| amount | number Сумма возврата в рублях |
| refundStatus | string Enum: "IN_PROGRESS" "COMPLETED" "DECLINED" Код состояния запроса на возврат |
Request samples
- PHP
- Node
- Java
<?php
$orderId = 'testOrder';
$refundId = 'testRefund';
/** @var \Raiffeisen\Ecom\Client $client */
$response = $client->getOrderRefund($orderId, $refundId);
print_r($response);
?>
Response samples
- 200
{- "code": "SUCCESS",
- "amount": 150,
- "refundStatus": "COMPLETED"
}