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

Cхема работы

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

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

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

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

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

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

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

АТОЛ Онлайн

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

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

OFD.ru

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

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

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

Чек-Онлайн

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

БИФИТ

Заключите договор с БИФИТ на аренду ККТ
Оплатите аренду ККТ и ФН. БИФИТ предоставит бесплатное подключение к ОФД Яндекс. При необходимости можно подключиться к другому ОФД. Для этого в ЛК найдите № ККТ и № ФН и выполните регистрацию в ОФД на свой выбор
Перейдите в личный кабинет БИФИТ для получения данных по подключенной кассе. Откройте пункт меню «Бифит Онлайн» и перейдите в раздел «Коннекторы ККТ». Создайте токен коннектора и привяжите к нему кассу. Скопируйте токен коннектора и заводской номер ККТ (идентификатор ККТ)
Подключите фискализацию в Личном кабинете 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 от имени покупателя по адресу: https://pay.raif.ru/pay/rfuture/

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

SDK

Использование js-библиотеки позволяет открывать форму в pop-up окне, что обеспечивает бесшовный сценарий для клиента. Также возможно выполнить кастомизацию интерфейса платежной формы и передать дополнительные поля Вы можете настроить название, логотип и цвет кнопок на форме в нашем конфигураторе: https://pay.raif.ru/pay/configurator/

Там же можно получить код для встраивания его в 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

Payload
JS
Node

Content type

application/json

Example

{"publicId": "000001680200002-80200002",
"orderId": "orderTest",
"amount": 1200,
"comment": "Покупка шоколадного торта",
"successUrl": "https://www.uniconf.ru/factories/krasny-octyabr/",
"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

string

Bearer secretKey

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

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

string

Bearer secretKey

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

Payload
PHP
Node
Java

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

string

Bearer secretKey

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

Content type

application/json

{"code": "SUCCESS",
"amount": 150,
"refundStatus": "COMPLETED"
}

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

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

path Parameters

orderId

required

string

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

header Parameters

Authorization

required

string

Bearer secretKey

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
Node

<?php

$orderId = 'testOrder';

/** @var