Download OpenAPI specification:Download
Для подключения перейдине на сайт.
По вопросам работы с API можно обращаться в службу поддержки Raiffeisenbank:
Чтобы принимать платежи:
Для интеграции платежной страницы используйте:
Демонстрация платежной формы:
В процессе платежа пользователь совершает следующие действия:
Данная схема работы требует наличие сертификации PCI DSS у вашей компании
Для проведения платежа с использованием собственной платежной формы, потребуется поддержать интеграцию с методами API Банка.
1. Создание платежа
Для проведения платежа первоначально необходимо создать платеж с помощью метода [Cоздание платежа]. В результате выполнения метода платеж будет сформирован в системе Банка.
В ответе метода вернется объект платежа со статусом NEW
.
SUCCESS
), если оплата пройдет по no3DS сценарию.2. Продолжение платежа
После того, как платеж был создан, необходимо продолжить обработку платежа с помощью метода [Продолжение платежа].
SUCCESS
), если оплата пройдет по 3DS v.2 frictionless flow.3. Вызов ACS эмитента для прохождения 3DS и ввода OTP-кода пользователем
Если в результате выполнения метода метода [Продолжение платежа] вернулся статус 3DS_PENDING
,
мерчанту необходимо перенаправить плательщика на страницу авторизации Банка-эмитента, а также отправить POST-запрос в сервис аутентификации эмитента.
acsUrl
3DS v.1:
Параметр | Описание |
---|---|
MD |
Информация для идентификации платежа. Параметр возвращается в ответе метода [Продолжение платежа]. |
PaReq |
Параметр, необходимый для аутентификации плательщика. Параметр возвращается в ответе метода [Продолжение платежа]. |
TermUrl |
URL-адрес на стороне мерчанта, на который ACS вернет ответ после прохождения 3DS аутентификации. |
3DS v.2:
Параметр | Описание |
---|---|
creq |
Данные платежной сессии, необходимые для проведения 3DS аутентификации. Параметр возвращается в ответе метода [Продолжение платежа]. |
Пример отправки POST-запроса в сторону ACS эмитента, для продолжения 3DS v.2:
export function createContinuePayment3ds2Iframe(acsUrl, creq) {
const container = document.getElementById('otp-page');
const iframe = window.document.createElement('iframe');
iframe.id = 'threeDs-2-solar-iframe';
iframe.style = 'height: 100%; width: 100%; overflow: hidden; position: absolute; top: 0; left: 0; background: white; z-index: 1000; border: none;';
const html = `
<body>
<div>
<form name="form" action="${acsUrl}" method="post">
<input type="hidden" name="creq" value="${creq}">
</form>
</div>
</body>
<script>
window.document.form.submit();
</script>
`;
container.appendChild(iframe);
iframe.contentWindow.document.open();
iframe.contentWindow.document.write(html);
}
После отправки POST-запроса с данными для продолжения 3DS, необходимо подписаться на прослушивание post message для завершения оплаты:
window.addEventListener('message', (event) => {
try {
if (typeof event.data !== 'string') return;
const { pares } = JSON.parse(event.data);
// Вызываем необходимый метод подтверждения 3DS для завершения платежа
} catch (error) {
console.error('Ошибка при обработке message:', error);
}
});
4. Подтверждение 3DS
Для завершения оплаты необходимо завершить обработку платежа, используя методы [Подтверждение 3DS v.1], либо [Подтверждение 3DS v.2].
Пример с завершением платежа по 3DS v.1:
window.parent.postMessage(JSON.stringify({
pares: paRes
}), '*');
Пример с завершением платежа по 3DS v.2:
window.parent.postMessage(JSON.stringify({
cres: document.getElementById('data').dataset.cres,
}), '*');
По закону от 22.05.2003 № 54-ФЗ "О применении контрольно-кассовой техники при осуществлении расчетов в Российской Федерации" при оплате товаров, работ или услуг необходимо формировать фискальный чек и отправлять его в налоговую с помощью кассы.
Клиенты Райффайзенбанка, подключившие интернет-эквайринг, также могут воспользоваться услугой фискализации чеков через онлайн-кассу. Пошаговые инструкции приведены ниже.
Поставщик кассового оборудования | ФФД 1.05 | ФФД 1.2 |
---|---|---|
АТОЛ Онлайн | + | + |
Билайн | - | + |
БИФИТ | + | - |
Чек-Онлайн | + | - |
Эвотор | + | + |
LIFE PAY | + | + |
ОFD.ru | + | + |
Orange Data | + | - |
Поддерживает ФФД 1.05 и ФФД 1.2
Поддерживает ФФД 1.2
Поддерживает ФФД 1.05
Поддерживает ФФД 1.05
Поддерживает ФФД 1.05 и ФФД 1.2
Поддерживает ФФД 1.05 и ФФД 1.2
Поддерживает ФФД 1.05 и ФФД 1.2
Для получения данных по подключенной кассе в OFD.ru перейдите в раздел Ferma в личном кабинете клиента и пролистайте до виджета "Реквизиты доступа". Скопируйте логин, пароль и идентификатор группы ККТ для подключения. Эти данные понадобятся на следующем шаге.
После этого чеки будут автоматически регистрироваться через выбранную кассу. Помимо автоматической фискализации чеков также доступна фискализация через API банка.
Поддерживает ФФД 1.05
Взаимодействие осуществляется по протоколу HTTP с использование методов POST
GET
PUT
DELETE
.
При отправке запросов на открытие платежной формы и создание заказа с открытием платежной формы, API возвращает ответ в формате HTML документа, ответы на остальные запросы возвращаются в формате JSON.
Для авторизации запросов необходимы:
publicId
- Идентификатор, котрый используется для открытия платежной формы и является публичным.secretKey
- Секретный ключ, который используется для межсервисного взаимодействия. Является приватным, необходимо хранить в защищенном месте и не передавать третьим лицам.Контур | Адрес обращения |
---|---|
Production | https://pay.raif.ru |
Test | https://pay-test.raif.ru |
Межсервисные запросы авторизуются посредством секретного ключа secretKey
. Параметр авторизации передается в заголовке Authorization
, значение которого формируется как Bearer + secretKey
Посмотреть боевой publicId
и сформировать secretKey
можно в Онлайн Банке, либо Личном Кабинете.
Инстуркции по формированию secretKey
можно посмотреть в Справочном Центре:
Для формирования secretKey
в тестовом контуре необходимо обратиться в службу поддержки ecom@raiffeisen.ru
Карты для тестовой среды:
PAN карты | Срок действия карты | CVV | OTP код | Сценарий платежа |
---|---|---|---|---|
4000001000000018 | 12/24 | 880 | 1234 | Успешная оплата |
4000001000000018 | 12/24 | 880 | 1111 | Неуспешная оплата |
Для полного цикла тестирования оплаты необходимо указывать сумму платежа больше 10 рублей.
Для полного цикла тестирования Райффайзенбанк предоставляет возможность использования демо-приложения для оплаты QR-кода от имени покупателя: WEB-приложение для оплаты по QR-коду
Приложение можно открыть в браузере любого устройства, имеющего камеру. После открытия приложения необходимо нажать на кнопку "Сканировать QR" (при необходимости разрешить браузеру доступ к камере) и отсканировать изображение тестового QR-кода.
Приложения банков не будут работать для оплаты QR-кодов в тестовой среде
Использование JS SDK позволяет открывать форму с frontend части в pop-up окне, либо осуществлять редирект пользователя на страницу Райффайзенбанка, что обеспечивает бесшовный сценарий оплаты для клиента.
Дополнительно можно кастомизировать интерфейс платежной формы и передавать дополнительные параметры для последующей оплаты. Настроить визуальную часть формы (название компании, логотип, цвет кнопок) можно в Конфигураторе платежной формы.
Также конфигуратор платежной формы позволяет получить код для встраивания его в JS-библиотеку.
Доступные SDK:
JS SDK позволяет открывать платежную форму с frontend части вашего приложения. При использовании остальных SDK для работы с платежной формой необходимо либо самостоятельно использовать методы, описанные в разделе [Платежная форма], либо использовать дополнительно JS SDK.
Также плагины для различных CMS можно найти в GitHub.
Вопросы по поддержке решений можно направлять в техническую поддержку: ecom@raiffeisen.ru
Простой способ для интеграции. Клиента необходимо перенаправить на платежную форму, передав параметры заказа.
[Схема взаимодействия].
При редиректе клиента на полученный URL откроется форма для оплаты. Для проверки суммы, поступившей от клиента, рекомендуется настроить Уведомление о платеже и сверять суммы созданного заказа и оплаты. Кастомизация интерфейса платежной формы или передача дополнительных полей в данном варианте интеграции недоступна.
publicId required | string Идентификатор мерчанта |
amount required | string Сумма платежа в рублях. Минимальный платеж по карте 10 рублей. Для копеек доступно два знака после точки |
comment | string Комментарий к заказу |
paymentDetails | string Назначение платежа в выписке, используется при оплате по СБП |
paymentMethod | string Метод оплаты |
locale | string Язык, используемый в интерфейса платежной формы. По умолчанию ru |
successUrl | string URL-адрес ресурса, куда будет перенаправлен плательщик в случае успешной оплаты |
failUrl | string URL-адрес ресурса, куда будет перенаправлен плательщик в случае неуспешной оплаты |
expirationDate | string Срок жизни заказа |
successSbpUrl | string Ссылка для автоматического возврата плательщика из приложения Банка в приложение или на сайт мерчанта. Ссылка должна содержать https:// для web-страниц или уникальную схему для мобильного приложения |
orderId | string Идентификатор заказа в системе мерчанта |
Метод позволяет создать заказ с открытием формы
publicId required | string Идентификатор мерчанта |
orderId | string <= 40 characters ^[A-z0-9-_.]+$ Идентификатор заказа в системе мерчанта |
amount required | number Сумма платежа в рублях. Минимальный платеж по карте 10 рублей. Для копеек доступно два знака после точки. |
comment | string <= 140 characters Комментарий. Не может быть пустым или содержать только пробелы. Может сождержать: |
successUrl | string <uri> URL-адрес ресурса, куда будет перенаправлен плательщик в случае успешной оплаты. |
failUrl | string <uri> URL-адрес ресурса, куда будет перенаправлен плательщик в случае неуспешной оплаты. |
object Дополнительные поля в формате key-value. Отображаются в реестрах | |
paymentMethod | string Enum: "ONLY_SBP" "ONLY_ACQUIRING" Способ оплаты. Если значение не передано, отображается общая форма |
locale | string <= 2 characters Enum: "ru" "en" Язык, используемый в интерфейса платежной формы. По умолчанию ru |
expirationDate | string <YYYY-MM-DDТHH24:MM:SS±HH:MM> Срок жизни заказа |
successSbpUrl | string <uri> Ссылка для автоматического возврата плательщика из приложения Банка в приложение или на сайт мерчанта. Ссылка должна содержать https:// для web-страниц или уникальную схему для мобильного приложения |
paymentDetails | string <= 140 characters Назначение платежа в выписке, используется при оплате по СБП |
{- "publicId": "000001680200002-80200002",
- "orderId": "order-test",
- "amount": 1200.37,
- "comment": "Покупка шоколадного торта",
- "extra": {
- "property1": "string",
- "property2": "string"
}, - "paymentMethod": "ONLY_ACQUIRING",
- "locale": "ru",
- "expirationDate": "2025-01-10T20:10:00+03:00",
- "paymentDetails": "Оплата товара №1 в магазине №1"
}
{- "timestamp": "2024-12-15T06:36:32+03:00",
- "status": 415,
- "error": "Unsupported Media Type",
- "path": "string"
}
Для работы с карточными платежами с вашей формой, потребуется PCI DSS сертификация вашей организации.
PCI DSS — стандарт информационной безопасности, принятый в индустрии платежных карт Visa и MasterCard. Соблюдать требования стандарта обязаны все компании, которые принимают оплату по картам на собственной платежной форме.
Для фискалзиации платежей можно использовать API фискализации банка
Перед началом работы рекомендуется ознакомиться со сценарием проведения платежа: Сценарий проведения платежа.
Для мерчантов с наличием сертификата PCI DSS
Метод позволяет создать платеж. Метод также может завершить платеж, если Банк-эмитент разрешит операцию по no3DS сценарию.
Примечания:
acsUrl
, threeDSMethodData
вернулись в ответе на запрос, необходимо выполнить шаг [Прохождение 3DS Method].publicId required | string Идентификатор мерчанта в системе Банка |
id | string <= 40 characters ^[A-z0-9-_.]+$ Идентификатор платежа. Если не передан будет сформирован на стороне Банка. Рекомендуем использовать UUID v4. |
amount required | number Сумма платежа в рублях. Минимальный платеж по карте 10 рублей. Для копеек доступно два знака после точки. |
object Заказ | |
extra | object Дополнительные поля в формате key-value. Отображаются в реестрах |
method required | string (WhitelabelPaymentMethod) Value: "CARD" Способ оплаты
|
required | object Данные плательщика |
{- "id": "payment-test",
- "amount": 540,
- "order": {
- "id": "order-test",
- "comment": "string"
}, - "extra": { },
- "method": "CARD",
- "parameters": {
- "cvv": "880",
- "pan": "4000001000000018",
- "month": 1,
- "year": 2030,
- "browserData": {
- "colorDepth": "24",
- "javaEnabled": true,
- "javaScriptEnabled": true,
- "language": "ru",
- "screenHeight": "1760",
- "screenWidth": "1800",
- "timezone": "300",
- "ipAddress": "77.77.77.77"
}
}
}
{- "id": "payment-test",
- "amount": 534.31,
- "order": {
- "id": "order-test",
- "comment": "Оплата товаров и услуг за заказ №1"
}, - "extra": {
- "email": "pavel@mail.ru"
}, - "method": "CARD",
- "status": {
- "value": "NEW",
- "date": "2024-12-31T10:00:00+03:00"
}
}
Для мерчантов с наличием сертификата PCI DSS
Метод используется для выполнения шага 3DS Method в процессе аутентификации.
Браузер плательщика должен отправить POST-запрос на acsUrl
, предоставленный системой, с передачей параметра threeDSMethodData
.
Примечания:
acsUrl
- Полный адрес, который необходимо вызвать из браузера плательщика. Параметр будет получен в результате выполнения метода [Создание платежа].threeDSMethodData
- JSON объект, закодированный в base64, содержащий информацию о транзакции, будет получен в результате выполнения метода [Создание платежа].threeDSMethodData required | string JSON, закодированный в base64, содержащий информацию о транзакции |
threeDSMethodData=eyJ0aHJlZURTQ29tcEluZm8iOiAiZXhhbXBsZSJ9
Для мерчантов с наличием сертификата PCI DSS
Метод позволяет получить состояние платежа, а также необходимые данные для прохождения 3DS аутентификации на любом этапе оплаты.
publicId required | string Идентификатор мерчанта в системе Банка |
id required | string Идентификатор платежа |
{- "id": "payment-test",
- "amount": 534.31,
- "order": {
- "id": "order-test",
- "comment": "Оплата товаров и услуг за заказ №1"
}, - "extra": {
- "email": "pavel@mail.ru"
}, - "method": "CARD",
- "status": {
- "value": "NEW",
- "date": "2024-12-31T10:00:00+03:00"
}
}
Для мерчантов с наличием сертификата PCI DSS
Метод используется для продолжения платежа. Метод также может завершить платеж в случае прохождения платежа по frictionless flow (3DS2).
3DS_PENDING
в ответе метода, необходимо отправить POST-запрос и перенаправить плательщика на адрес эмитента, подробнее данный шаг описан в [Сценарии проведения платежа].3DS_PENDING
в ответе метода, необходимо завершить платеж, используя методы завершения 3DS с параметрами, полученными от эмитента.publicId required | string Идентификатор мерчанта в системе Банка |
id required | string Идентификатор платежа |
{- "id": "payment-test",
- "amount": 534.31,
- "order": {
- "id": "order-test",
- "comment": "Оплата товаров и услуг за заказ №1"
}, - "extra": {
- "email": "pavel@mail.ru"
}, - "method": "CARD",
- "status": {
- "value": "3DS_PENDING",
- "date": "2024-12-31T10:00:00+03:00"
}, - "parameters": {
- "threeDSVersion": "V1",
- "threeDS": {
- "pareq": "eNqdmU9P2zAQhu+L7U",
- "md": "M139anFAI94ana93)a3="
}
}
}
Для мерчантов с наличием сертификата PCI DSS
Метод используется для прохождения 3DS v.1 и завершения платежа.
Вызывать метод необходимо при получении статуса 3DS_PENDING
с передачей параметра pares
, который будет получен от Банка-Эмитента через браузер плательщика.
publicId required | string Идентификатор мерчанта в системе Банка |
id required | string Идентификатор платежа |
pares required | string Зашифрованный ответ от ACS эмитента с результатами 3DS авторизации, необходимыми для завершения платежа. Параметр должен быть получен браузером плательщика и передан в Райффайзенбанк. |
{- "pares": "eJzNWVmvo0iy/iutnkdUzW6bketImew2YLMaeGkBxixmM4tZfv3gc6qqq2tq5va9uiMNL0CQGRmRsXwRyd5K2zjmzDga2vhtr8ZdFyTxL9n186/Z9XfmFjLrh"
}
{- "id": "payment-63853012",
- "amount": 534.31,
- "order": {
- "id": "order-63853012",
- "comment": "Оплата товаров и услуг за заказ №1"
}, - "extra": {
- "email": "pavel@mail.ru"
}, - "method": "CARD",
- "status": {
- "value": "SUCCESS",
- "date": "2025-11-29T19:43:54+03:00"
}, - "parameters": {
- "rrn": "935014591810",
- "authCode": "259AA"
}
}
Для мерчантов с наличием сертификата PCI DSS
Метод используется для прохождения 3DS v.2 и завершения платежа.
Вызывать метод необходимо при получении статуса 3DS_PENDING
с передачей параметра cres
, который будет получен от Банка-Эмитента через браузер плательщика.
publicId required | string Идентификатор мерчанта в системе Банка |
id required | string Идентификатор платежа |
cres required | string Зашифрованный ответ от ACS эмитента с результатами 3DS авторизации, необходимыми для завершения платежа. Параметр должен быть получен браузером плательщика и передан в Райффайзенбанк. |
{- "cres": "eJzNWVmvo0iy/iutnkdUzW6bketImew2YLMaeGkBxixmM4tZfv3gc6qqq2tq5va9uiMNL0CQGRmRsXwRyd5K2zjmzDga2vhtr8ZdFyTxL9n186/Z9XfmFjLrh"
}
{- "id": "payment-63853012",
- "amount": 534.31,
- "order": {
- "id": "order-63853012",
- "comment": "Оплата товаров и услуг за заказ №1"
}, - "extra": {
- "email": "pavel@mail.ru"
}, - "method": "CARD",
- "status": {
- "value": "SUCCESS",
- "date": "2025-11-29T19:43:54+03:00"
}, - "parameters": {
- "rrn": "935014591810",
- "authCode": "259AA"
}
}
Для реализации взаимодействия с партнёром Райффайзенбанк предоставляет API для:
Метод позволяет получить статус транзакции. Необходимо проверять сумму, так как у плательщика есть возможность ее изменить.
orderId required | string <= 40 characters Идентификатор заказа в системе мерчанта |
{- "code": "SUCCESS",
- "transaction": {
- "id": 120059,
- "orderId": "order-test",
- "status": {
- "value": "SUCCESS",
- "date": "2024-12-31T17:00:00+03:00"
}, - "paymentMethod": "acquiring",
- "paymentParams": {
- "rrn": "935014591810",
- "authCode": "259AA"
}, - "amount": 12500.5,
- "comment": "Покупка шоколадного торта",
- "extra": {
- "apiClient": "Payform Software",
- "apiClientVersion": "1.0.0"
}
}
}
Метод позволяет выполнить отмену/возврат по платежу, как полную, так и частичную. В случае с СБП выполняется только возврат.
Для мерчантов с подключенной фискализацией метод также позволяет сформировать фискальный чек по возврату. Для этого необходимо в теле запроса передать данные чека в объекте receipt, чек возврата будет сформирован автоматически.
orderId required | string <= 40 characters Идентификатор заказа в системе мерчанта |
refundId required | string Уникальный идентификатор запроса на возврат в системе мерчанта |
amount required | number Сумма возврата в рублях |
paymentDetails | string <= 140 characters Назначение платежа для СБП. Не может быть пустым или содержать только пробелы. Может сождержать: |
{- "amount": 1200,
- "paymentDetails": "Покупка в магазине №1"
}
{- "code": "SUCCESS",
- "amount": 1200,
- "refundStatus": "COMPLETED",
- "receipt": {
- "customer": {
- "email": "customer@test.ru",
- "name": "Иванов Иван Иванович",
- "extra": { }
}, - "items": [
- {
- "name": "Шоколадный торт",
- "price": 1200,
- "quantity": 1,
- "amount": 1200,
- "paymentObject": "COMMODITY_MARKING_WITH_CODE",
- "paymentMode": "FULL_PREPAYMENT",
- "measurementUnit": "PIECE",
- "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": "287381373424"
}, - "marking": {
- "quantity": {
- "numerator": 1,
- "denominator": 3
}, - "code": {
- "format": "GS1M",
- "value": "MDEwNDYwNzQyODY3OTA5MDIxNmVKSWpvV0g1NERkVSA5MWZmZDAgOTJzejZrU1BpckFwZk1CZnR2TGJvRTFkbFdDLzU4aEV4UVVxdjdCQmtabWs0PQ=="
}
}
}
], - "payments": [
- {
- "type": "PREPAID",
- "amount": 1200
}
]
}
}
Метод позволяет получить статус по отмене или возврату.
orderId required | string <= 40 characters Идентификатор заказа в системе мерчанта |
refundId required | string Уникальный идентификатор запроса на возврат в системе мерчанта |
<?php
$orderId = 'order-test';
$refundId = 'refund-test';
/** @var \Raiffeisen\Ecom\Client $client */
$response = $client->getOrderRefund($orderId, $refundId);
print_r($response);
?>
{- "code": "SUCCESS",
- "amount": 1200,
- "refundStatus": "COMPLETED"
}
Метод позволяет получить данные о заказе.
orderId required | string <= 40 characters Идентификатор заказа в системе мерчанта |
<?php
$orderId = 'order-test';
/** @var \Raiffeisen\Ecom\Client $client */
$response = $client->getOrder($orderId);
print_r($response);
?>
{- "amount": 12500.5,
- "comment": "Покупка шоколадного торта",
- "extra": {
- "apiClient": "Payform Software"
}, - "status": {
- "value": "NEW",
- "date": "2024-12-31T10:00:00+03:00"
}, - "expirationDate": "2024-12-31T17:00:00+03:00"
}
Метод позволяет отменить заказ, если он не был оплачен. После отмены страница оплаты будет недоступна.
orderId required | string <= 40 characters Идентификатор заказа в системе мерчанта |
<?php
$orderId = 'order-test';
/** @var \Raiffeisen\Ecom\Client $client */
$client->deleteOrder($orderId);
?>
{- "code": "string",
- "message": "string"
}
Метод позволяет получить по заказу список чеков, которые успешно зарегистрированы в ОФД и имеют статус DONE
. По умолчанию возвращаются как чеки прихода, так и чеки возврата. Чтобы получить чеки определенного типа, необходимо в строке запроса передать дополнительный параметр receiptType.
Если ни один чек не найден, в ответ вернется 200 OK и пустой массив.
orderId required | string <= 40 characters Идентификатор заказа в системе мерчанта |
receiptType | string Тип чека:
|
<?php
$orderId = 'order-test';
/** @var \Raiffeisen\Ecom\Client $client */
$response = $client->getOrderReceipts($orderId);
print_r($response);
?>
[- {
- "receiptNumber": "3000827351832",
- "receiptType": "REFUND",
- "status": "DONE",
- "orderNumber": "order-test",
- "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
}
]
}
]
Метод позволяет получить чек возврата по идентификатору заказа и идентификатору возврата.
orderId required | string <= 40 characters Идентификатор заказа в системе мерчанта |
refundId required | string Уникальный идентификатор запроса на возврат в системе мерчанта |
<?php
$orderId = 'order-test';
$refundId = 'refund-test';
/** @var \Raiffeisen\Ecom\Client $client */
$response = $client->getOrderRefundReceipt($orderId, $refundId);
print_r($response);
?>
{- "receiptNumber": "3000827351831",
- "receiptType": "REFUND",
- "status": "DONE",
- "orderNumber": "order-test",
- "total": 1200,
- "customer": {
- "email": "customer@test.ru",
- "name": "Иванов Иван Иванович",
- "extra": { }
}, - "items": [
- {
- "name": "Шоколадный торт",
- "price": 1200,
- "quantity": 1,
- "amount": 1200,
- "paymentObject": "COMMODITY_MARKING_WITH_CODE",
- "paymentMode": "FULL_PREPAYMENT",
- "measurementUnit": "PIECE",
- "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": "287381373424"
}, - "marking": {
- "quantity": {
- "numerator": 1,
- "denominator": 3
}, - "code": {
- "format": "GS1M",
- "value": "MDEwNDYwNzQyODY3OTA5MDIxNmVKSWpvV0g1NERkVSA5MWZmZDAgOTJzejZrU1BpckFwZk1CZnR2TGJvRTFkbFdDLzU4aEV4UVVxdjdCQmtabWs0PQ=="
}
}
}
], - "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.
Для проверки подлинности уведомления по возврату к данным добавляется подпись в заголовке x-api-signature-sha256, полученная на основе общего секретного ключа и контрольной строки amount|publicId|refund.id|status.value|status.date
с помощью HMAC-SHA-256.
Необходимо проверять сумму, так как у клиентов есть возможность ее изменить.
Уведомления отправляются с IP 193.28.44.23
event | string Value: "payment" Тип операции |
any (Transaction) Данные по операции |
{- "event": "payment",
- "transaction": {
- "id": 120059,
- "orderId": "order-test",
- "status": {
- "value": "SUCCESS",
- "date": "2024-12-31T10:00:00+03:00"
}, - "paymentMethod": "acquiring",
- "paymentParams": {
- "rrn": "935014591810",
- "authCode": "259AA"
}, - "amount": 12500.5,
- "comment": "Покупка шоколадного торта",
- "extra": {
- "apiClient": "Payform Software",
- "apiClientVersion": "1.0.0"
}
}
}
{- "refund": {
- "id": "refund-test",
- "ecom": {
- "rrn": "556435345345435",
- "authCode": "123456AA"
}, - "amount": 1500.2,
- "status": {
- "value": "COMPLETED",
- "date": "2024-12-31T15:00:00+03:00"
}, - "paymentParams": {
- "transactionId": 935014591810,
- "orderId": "order-test"
}
}
}
Уведомления будут подписываться ключем, переданным в заголовке авторизации.
callbackUrl required | string URL-адрес для приема уведомлений |
{
}
{
}
Для подключения отправки реестров необходимо написать на ecom@raiffeisen.ru
Реестры по платежам отправляются на ежедневной основе.
В случае отсутствия операций за день, реестр на следующий день не отправляется.
Формат реестра:
Наименование колонки | Значение |
---|---|
Мерчант | Идентификатор в системе банка |
Дата операции МСК | Дата и время проведения операции |
Тип | Тип операции |
id заказа | Id заказа в системе партнера (orderId) |
id возврата | Id возврата в системе партнера (refundId) |
Комментарий | Комментарий к заказу (comment) |
Способ оплаты | Instant Payment QR - при оплате по СБП, Название платежной системы - по Эквайрингу |
Данные оплаты | QR id - для СБП, authCode и rnn -для Эквайринга |
id клиента | СБП - маскированный код плательщика. Для Эквайринга - маскированный номер карты |
Сумма | Сумма транзакции (amount) |
Комиссия | Комиссия по транзакции |
Дополнительные поля | Дополнительная информация (extra) |
Пример выписки по платежам интернет-эквайринга
Методы позволяют получить список операций и итоговые суммы за определенный промежуток времени. Возможно использование методов для закрытия кассового периода.
Отчёт по транзакциям за указанный период (не более трёх дней).
from required | string <ENCODE 'YYYY-MM-DDТHH24:MM:SS±HH:MM'> Дата и время начала выборки |
to required | string <ENCODE 'YYYY-MM-DDТHH24:MM:SS±HH:MM'> Дата и время окончания выборки |
operationTypes | string Enum: "Payment" "Refund" Тип операции. Если значение не передано - выгружаются все типы операций |
qrId | string Example: qrId=AD1F2CD7212E48FA919AB52EF0AEFB33 Идентификатор QR-кода. Если значение не передано - выгружаются все операции по мерчанту |
{- "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
}
}
}
Получение детализированного отчёта по транзакциям за указанный период (не более трёх дней).
from required | string <ENCODE 'YYYY-MM-DDТHH24:MM:SS±HH:MM'> Дата и время начала выборки |
to required | string <ENCODE 'YYYY-MM-DDТHH24:MM:SS±HH:MM'> Дата и время окончания выборки |
operationTypes | string Enum: "Payment" "Refund" Тип операции. Если значение не передано - выгружаются все типы операций |
qrId | string Example: qrId=AD1F2CD7212E48FA919AB52EF0AEFB33 Идентификатор QR-кода. Если значение не передано - выгружаются все операции по мерчанту |
{- "sbp": {
- "payment": [
- {
- "orderId": "order-test",
- "amount": 77,
- "transactionDate": "2024-12-31T10:00:00+03:00",
- "paymentSystem": "Instant Payment QR",
- "paymentDetails": "Благотворительное пожертвование",
- "transactionId": 178657,
- "clientId": "007910******4567",
- "qrId": "AS1A007L7B8IPA1F8CBQ8RK2D27FHST9",
- "sbpTransactionId": "A23091339574920E000009529E6B66DF",
- "orderComment": "Комментарий",
- "fee": 0.31
}
], - "refund": [
- {
- "orderId": "order-test-1",
- "amount": 17,
- "transactionDate": "2024-12-31T10:00:00+03:00",
- "paymentSystem": "Instant Payment QR",
- "paymentDetails": "Возврат денежных средств",
- "transactionId": 178658,
- "clientId": "007910******4567",
- "qrId": "AS1A007L7B8IPA1F8CBQ8RK2D27FHST9",
- "sbpTransactionId": "B229701403532102000016268EEA632B",
- "refundId": "refund-1",
- "fee": 0
}
]
}, - "card": {
- "payment": [
- {
- "orderId": "order-test-2",
- "amount": 14,
- "transactionDate": "2024-12-31T10:50:00+03:00",
- "paymentSystem": "VISA",
- "paymentDetails": "Назначение платежа",
- "transactionId": 5252420,
- "clientId": "200043****823",
- "authCode": "259AA",
- "rrn": "935014591810",
- "orderComment": "Благотворительное пожертвование",
- "fee": 0.38
}
], - "refund": [
- {
- "orderId": "order-test-3",
- "amount": 13,
- "transactionDate": "2022-12-14T10:01:24.84+03:00",
- "paymentSystem": "VISA",
- "paymentDetails": "Назначение платежа",
- "transactionId": 5252440,
- "clientId": "200043****823",
- "authCode": "259AA",
- "rrn": "935014591810",
- "refundId": "refund-2",
- "fee": 0
}
]
}
}
Ответ любого метода содержит код сообщения (code). Если в процессе обработки любого запроса произойдет логическая ошибка, API вернет описание ошибки (message).
Описание основных ошибок:
code | message |
---|---|
ERROR.NOT_FOUND | Счет не найден у данного партнера |
ERROR.REFUND_INSUFFICIENT_FUNDS | Сумма возврата больше суммы остатка по платежу |
ERROR.INVALID_REQUEST | Некорректные параметры запроса |
RECEIPT_VALIDATION_FAILED | Чек не прошел валидацию. Причина: * |
В таблице отражены важные изменения в методах API.
Дата | Описание |
---|---|
19.12.2024 | * Добавлены методы по работе с формой клиента |
24.07.2024 | * Объединена документация для чеков по ФФД 1.05 и ФФД 1.2 |
10.07.2024 | * Добавлены уведомления на операции возвратов |
18.04.2024 | * В методы сверок операций за период добавлен новый параметр комиссия |
29.03.2023 | * Внесены ограничения по полям comment при создании заказов и paymentDetails при возвратах |
16.12.2022 | * Добавлены методы для сверки операций по картам и СБП |
11.10.2022 | * Добавлены SDK с описанием в методах |
30.09.2022 | * Реализована поддержка авансовых чеков и чеков частичной предоплаты |
26.08.2022 | * Добавлен ФФД 1.2 для сервиса "АТОЛ Онлайн" |
29.07.2022 | * Изменены хосты : * Боевой с e-commerce.raiffeisen.ru на pay.raif.ru * Тествый c ecom.test.raiffeisen.ru на pay-test.raif.ru |
27.07.2022 | * Добавлен параметр paymentDetails, позволяет указать назначение платежа для вашей выписки для операций СБП |
30.05.2022 | * Добавлен параметр successSbpUrl, который позволяет передать ссылку для перенаправления клиента, из приложения банка, в случае успешной операции |
17.05.2022 | * Добавлен метод открытия платежной формы через POST-метод |
15.04.2022 | * В документацию добавлен партнер "БИФИТ", приведена инструкция по подключению онлайн-кассы сервиса БИФИТ * Скорректированы примеры запроса на сохранение чека (удалены параметры для агентских операций) * Дополнено правило заполнения номеклатурного кода для партнера "БИФИТ" * Небольшие правки по тексту |
25.03.2022 | * В модель чека добавлен параметр paymentMode для передачи способа расчёта (100% предоплата, полный расчет) |
05.03.2022 | * Расширен API для оформления возврата для возможности пробить чек. В т.ч. в POST-метод добавлен новый объект receipt для передачи данных чека * Добавлен API для получения массива чеков по заказу * Добавлен API для получения чека возврата по заказу и идентификатору возврата * Реализовано переключение через кнопки "с чеком/без чека" для API, где возможен один из вариантов * Добавлен перевод документации на английский язык |
18.01.2022 | * Для фискализации в чек прихода добавлены новые параметры для агентских операций: agentType, supplierInfo |
30.12.2021 | * Обновлена диаграмма последовательности UML в разделе "Схема работы" |
29.10.2021 | * Добавлены методы для отмены заказа и получения его статуса |
21.10.2021 | * Добавлен параметр expirationDate - ответчающий за срок жизни заказа |