Интеграция 1С-Битрикс с платёжной системой iPay (Беларусь)
При подключении iPay к магазину на Битрикс мы часто сталкиваемся с типовыми ошибками: неправильный расчёт суммы в копейках, сбой уведомлений из-за пропущенной проверки подписи, конфликты с кешированием на странице успеха. В этой статье разберём, как этого избежать, и покажем рабочий пример интеграции с нуля. Наш опыт показывает: подключение iPay под ключ занимает от 5 до 10 рабочих дней, включая получение тестового доступа, разработку кастомного обработчика и фискализацию по 54-ФЗ (если требуется). Мы гарантируем корректную обработку всех статусов и возвратов, а также полную документацию для вашей команды.
iPay — белорусский платёжный агрегатор от компании «Дежур», работающий на базе процессинга НКФО «Открытое акционерное общество «Небанковская кредитно-финансовая организация». Шлюз поддерживает карты Visa, Mastercard, Белкарт и платежи через ЕРИП. Для малого и среднего бизнеса в Беларуси iPay часто выступает альтернативой прямому подключению к банкам — с упрощённой документацией и быстрым onboarding.
Какие варианты интеграции iPay поддерживает?
iPay предоставляет два варианта интеграции:
Hosted Payment Page — покупатель перенаправляется на страницу iPay, выбирает способ оплаты, платит. Магазин получает уведомление. Минимальные требования к безопасности на стороне магазина — PCI DSS не требуется.
API-интеграция — данные карты принимаются формой на сайте магазина и передаются в iPay. Требует PCI DSS или токенизации через JS-библиотеку iPay.
Для большинства внедрений на Битрикс используется Hosted Page как более простой и безопасный вариант.
| Характеристика | Hosted Page | API-интеграция |
|---|---|---|
| Требования к безопасности | Не требуется PCI DSS | Требуется PCI DSS или токенизация |
| Сложность внедрения | Низкая | Средняя |
| Контроль дизайна | Ограничен | Полный |
| Время разработки | 2-3 дня | 5-7 дней |
Как реализовать кастомный обработчик iPay на Битрикс?
Официального модуля 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": "2023-06-15T14:32:11Z",
"signature": "sha256_hash_here"
}
Верификация подписи — SHA-256 от строки payment_id + order_id + amount + currency + shop_secret. Без проверки подписи любой желающий может отправить фальшивое уведомление об оплате. Алгоритм SHA-256 описан в Wikipedia. Источник: Википедия
Статусы: 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 рабочих дней.
Что входит в нашу работу по интеграции iPay?
- Разработка кастомного платежного обработчика для Битрикс.
- Настройка уведомлений и проверки подписи.
- Реализация возвратов через API.
- Интеграция с 1С (опционально) для синхронизации статусов.
- Тестирование в песочнице и на боевом окружении.
- Документация и передача доступов.
Мы оцениваем проект бесплатно — напишите нам, и мы подготовим точную смету. Наши специалисты имеют 5-летний опыт работы с Битрикс и более 50 успешных интеграций платёжных систем.