Налаштування інтернет-еквайрингу на 1С-Бітрікс

Налаштування інтернет-еквайрингу на 1С-Бітрікс

Інтернет-еквайринг — один з перших модулів, що налаштовують при запуску інтернет-магазину. На практиці «підключити еквайринг» означає кілька окремих завдань: реєстрацію в платіжній системі, встановлення та налаштування обробника в 1С-Бітрікс, налаштування callback-повідомлень, тестування та обробку вимог фіскального законодавства за потреби. Кожна з них містить нюанси, що не очевидні на етапі налаштування.

Вибір платіжної системи та еквайрингу

Вибір еквайрингу впливає на технічну реалізацію. Основні варіанти для російського ринку:

Встановлення та налаштування обробника

Стандартний шлях для готових модулів:

1. Встановлення модуля — через Marketplace → Каталог рішень або завантаженням архіву в /bitrix/updates/
2. Створення платіжної системи — Магазин → Налаштування → Платіжні системи → Додати
3. Налаштування параметрів — заповнення полів shopId/merchantId, secretKey/password, URL повідомлень

Критично важливий параметр при налаштуванні — URL для повідомлень (callback URL). Для стандартного обробника 1С-Бітрікс це:

https://myshop.ru/bitrix/tools/sale_ps_result.php

Цей URL повинен:

• Бути доступним з серверів платіжної системи (не захищений basic auth)
• Працювати без редиректів
• Повертати HTTP 200 при успішній обробці

Структура обробника платіжної системи

Якщо потрібен кастомний обробник або готовий модуль не підходить:

// /local/php_interface/include/sale_payment/my_gateway/handler.php
use Bitrix\Sale\PaySystem;

class MyGatewayHandler extends PaySystem\ServiceHandler
{
    // Ініціює платіж — перенаправляє покупця
    public function initiatePay(
        \Bitrix\Sale\Payment $payment,
        \Bitrix\Main\Request $request
    ): PaySystem\ServiceResult {
        $result = new PaySystem\ServiceResult();
        // Формуємо URL платіжного шлюза та редиректимо
        $result->setPaymentUrl($this->buildPaymentUrl($payment));
        return $result;
    }

    // Обробляє вхідне повідомлення від шлюза
    public function processRequest(
        \Bitrix\Sale\Payment $payment,
        \Bitrix\Main\Request $request
    ): PaySystem\ServiceResult {
        $result = new PaySystem\ServiceResult();

        if ($this->verifyRequest($request) && $this->isPaymentSucceeded($request)) {
            $payment->setPaid('Y');
            $result->setOperationType(PaySystem\ServiceResult::MONEY_COMING);
        }

        return $result;
    }

    // Перевіряємо підпис запиту
    private function verifyRequest(\Bitrix\Main\Request $request): bool
    {
        $sign = $request->get('sign');
        $expected = hash_hmac('sha256',
            $request->get('orderId') . $request->get('amount'),
            $this->getBusinessValue(null, 'SECRET_KEY')
        );
        return hash_equals($expected, $sign);
    }
}

Метадані обробника (.description.php) та налаштування (.settings.php) відповідають стандарту sale.paysystem.handler.

Тестування

Обов'язковий мінімум перед запуском:

• Успішна оплата тестовою карткою → замовлення переходить у статус «Оплачено»
• Callback надходить та обробляється коректно
• Повторна оплата вже оплаченого замовлення не дублює статус
• Покупець закрив браузер після оплати — статус все одно оновлюється через callback

Терміни