Інтеграція 1С-Бітрікс із платіжною системою Сбербанк Онлайн
Типова ситуація: інтернет-магазин на Бітрікс працює, замовлення надходять, але покупці телефонують і просять «виставити рахунок через Сбер» — тому що не бачать потрібної кнопки на сторінці оплати. Підключення Сбербанк Онлайн до Бітрікс закриває цей запит і попутно виявляє кілька технічних нюансів, які на етапі «просто встановимо модуль» не очевидні.
Як працює платіжний шлюз Сбербанку
Сбербанк Онлайн працює через REST API еквайрингу (securepayments.sberbank.ru/payment/rest/ для бойового середовища, 3dsec.sberbank.ru/payment/rest/ для тестового). Схема взаємодії:
- Магазин викликає
register.do— реєструє замовлення в системі Сбербанку, отримуєorderIdіformUrl - Покупця редиректять на
formUrl— сторінку оплати Сбербанку - Після оплати Сбербанк перенаправляє покупця на
returnUrlі надсилає нотифікацію наfailUrlабо виконує callback - Магазин викликає
getOrderStatus.doдля фінальної перевірки статусу
Критично важливо не покладатися лише на returnUrl для підтвердження оплати — покупець може закрити вкладку після оплати, не дочекавшись редиректу. Завжди потрібен callback або періодичне опитування getOrderStatus.do.
Технічна інтеграція з 1С-Бітрікс
В екосистемі Бітрікс Сбербанк Онлайн реалізується як обробник платіжної системи модуля sale. Є кілька шляхів.
Готовий модуль з Маркетплейсу. Офіційний модуль від Сбербанку (sberbank.ecom) доступний на marketplace.1c-bitrix.ru. Після встановлення в розділі Магазин → Налаштування → Платіжні системи з'являється новий тип із полями userName, password (або token для нової схеми автентифікації). Модуль реєструє обробник \Sale\Handlers\PaySystem\SberbankHandler і webhook-URL вигляду /bitrix/tools/sale_ps_result.php.
Кастомний обробник потрібен, коли: використовується нестандартна схема замовлень, потрібна інтеграція з 1С для автоматичної зміни статусів, або готовий модуль конфліктує з іншими компонентами. Розміщується в /local/php_interface/include/sale_payment/sberbank_custom/, структура стандартна для Sale PaySystem.
Ключові параметри при реєстрації замовлення
Виклик register.do вимагає обов'язкових параметрів:
-
orderNumber— унікальний номер у системі магазину (зазвичайBXORDER_{ID}) -
amount— сума в копійках (поширена помилка — передавати в рублях) -
returnUrl— URL повернення після оплати -
currency— код валюти (643 для рублів за ISO 4217)
Для роботи фіскалізації (54-ФЗ) у запит додається об'єкт orderBundle з товарними позиціями, ставками ПДВ і ознаками предмета розрахунку. Без orderBundle каса Сбербанку не сформує чек — це часта причина претензій від податкової до магазинів, які «нібито підключили онлайн-касу».
Обробка повідомлень та статуси
Сбербанк надсилає POST-повідомлення на checkUrl при зміні статусу транзакції. Обробник callback у Бітрікс повинен:
- Прийняти POST, розпарсити
mdOrderіorderNumber - Викликати
getOrderStatus.doдля отримання актуального статусу (не довіряти даним із callback без верифікації) - При статусі
2(оплачено) викликати$payment->setPaid('Y')і зберегти транзакцію - Повернути відповідь
{"errorCode": 0}— інакше Сбербанк повторюватиме спроби
Таблиця статусів getOrderStatus.do:
| Код | Значення | Дія |
|---|---|---|
| 0 | Замовлення зареєстровано | Очікувати |
| 1 | Сума преавторизована | Для двостадійних платежів |
| 2 | Оплачено | Підтвердити в Бітрікс |
| 3 | Авторизацію скасовано | Скасувати замовлення |
| 4 | Повернення виконано | Оновити статус |
| 6 | Авторизацію відхилено | Повідомити покупця |
Двостадійна оплата
Для товарів з відкладеним відвантаженням (передзамовлення, склад) використовується двостадійна схема: registerPreAuth.do блокує суму на картці, deposit.do — списує по факту відвантаження. Сбербанк надає обидва методи, але двостадійна оплата потребує окремого підключення в договорі еквайрингу. У Бітрікс це реалізується через розділення обробника на два етапи та додаткову кнопку «Підтвердити оплату» в адміністративній частині замовлення.
Реальний кейс: проблема дублювання платежів
Інтернет-магазин електроніки на Бітрікс 21. Після переходу з тестового середовища на бойове близько 3% транзакцій дублювалося — покупець платив один раз, у замовленні фіксувалися два платежі. Причина: обробник returnUrl і callback надходили майже одночасно, обидва встигали викликати setPaid('Y'). Рішення — додати перевірку $payment->isPaid() перед підтвердженням і використовувати блокування через \Bitrix\Main\Application::getConnection()->lock() під час обробки транзакції.
Тестування
Тестове середовище Сбербанку (3dsec.sberbank.ru) працює з тестовими картками з документації. Обов'язково перевірте:
- Успішну оплату з підтвердженням через callback
- Скасування на сторінці оплати (покупець натиснув «Назад»)
- Таймаут сесії (за замовчуванням 1200 секунд — Сбербанк скасовує незавершені замовлення)
- Коректність формування чека при увімкненій касі
Терміни інтеграції залежать від конфігурації: встановлення готового модуля без каси — від 1 до 2 днів. Повна інтеграція з 54-ФЗ, двостадійною оплатою та підлаштуванням під нестандартну структуру замовлень — від 3 до 7 робочих днів.