Интеграция 1С-Битрикс с платёжной системой iPay (Беларусь)
iPay — белорусский платёжный агрегатор от компании «Дежур», работающий на базе процессинга НКФО «Открытое акционерное общество «Небанковская кредитно-финансовая организация». Шлюз поддерживает карты Visa, Mastercard, Белкарт и платежи через ЕРИП. Для малого и среднего бизнеса в Беларуси iPay часто выступает альтернативой прямому подключению к банкам — с упрощённой документацией и быстрым onboarding.
Как работает iPay
iPay предоставляет два варианта интеграции:
Hosted Payment Page — покупатель перенаправляется на страницу iPay, выбирает способ оплаты, платит. Магазин получает уведомление. Минимальные требования к безопасности на стороне магазина — PCI DSS не требуется.
API-интеграция — данные карты принимаются формой на сайте магазина и передаются в iPay. Требует PCI DSS или токенизации через JS-библиотеку iPay.
Для большинства внедрений на Битрикс используется Hosted Page как более простой и безопасный вариант.
Эндпоинт: https://api.ipay.by/ (боевая среда), https://sandbox.ipay.by/ (тест).
Техническая интеграция с Битрикс
Официального модуля iPay на Маркетплейсе Битрикс нет. Реализуется как кастомный обработчик в /local/php_interface/include/sale_payment/ipay_belarus/.
Инициализация платежа — POST-запрос к /api/v1/payments:
{
"shop_id": "YOUR_SHOP_ID",
"order_id": "BXORDER_12345",
"amount": 5990,
"currency": "BYN",
"description": "Заказ №12345 в магазине Example",
"success_url": "https://yourshop.by/thank-you/?order=12345",
"fail_url": "https://yourshop.by/payment-error/?order=12345",
"notify_url": "https://yourshop.by/bitrix/tools/sale_ps_result.php",
"lang": "ru"
}
Сумма передаётся в белорусских копейках (BYN × 100). iPay возвращает payment_id и payment_url — на последний выполняется редирект покупателя.
Обработка уведомлений
iPay отправляет POST на notify_url при изменении статуса платежа. Тело уведомления:
{
"payment_id": "ipay_txn_98765",
"order_id": "BXORDER_12345",
"status": "PAID",
"amount": 5990,
"currency": "BYN",
"paid_at": "2024-06-15T14:32:11Z",
"signature": "sha256_hash_here"
}
Верификация подписи — SHA-256 от строки payment_id + order_id + amount + currency + shop_secret. Без проверки подписи любой желающий может отправить фальшивое уведомление об оплате.
Статусы: PAID (оплачен), FAILED (ошибка), CANCELLED (отменён), EXPIRED (истёк срок).
Срок жизни платёжной сессии
По умолчанию iPay даёт покупателю 15 минут на завершение оплаты. По истечении сессия закрывается со статусом EXPIRED. В Битрикс это означает, что обработчик должен уметь работать с таймаутами: при получении EXPIRED — уведомить покупателя и предложить новую попытку без создания дублирующего заказа.
Срок можно увеличить до 60 минут через параметр expire_at в запросе создания платежа — полезно для B2B-заказов, где решение о покупке принимается дольше.
Возвраты через API
iPay поддерживает возврат через API: POST к /api/v1/payments/{payment_id}/refund с параметрами amount (частичный или полный возврат) и reason. Из административной части Битрикс это можно реализовать как кнопку «Возврат» на странице заказа — метод ProcessRequestRefund обработчика вызывает API и обновляет статус платежа.
Реальный кейс: конфликт с кешированием страницы
Белорусский интернет-магазин детских товаров. После успешной оплаты через iPay покупатели иногда видели страницу с реквизитами старого заказа другого пользователя. Причина: страница «спасибо за заказ» кешировалась nginx, и при редиректе с success_url возвращался кешированный ответ. Решение: добавить заголовок Cache-Control: no-store, no-cache для URL страниц заказа и убедиться, что параметр ?order= читается динамически из Битрикс-сессии, а не из URL.
Тестирование
В тестовой среде iPay (sandbox.ipay.by) тестовые карты публикуются в личном кабинете разработчика. Для ЕРИП-оплаты в тесте используется эмулятор — нотификация приходит автоматически через 30 секунд после создания счёта.
Сроки подключения: получение тестового доступа — 1–2 дня. Разработка обработчика — 2–3 дня. Боевое подключение с проверкой документов компании — 5–10 рабочих дней.