Інтеграція 1С-Бітрікс із платіжною системою Альфа-Банк еквайринг

Інтеграція 1С-Bitrix з платіжною системою Alfa-Bank

Alfa-Bank — одна з розповсюджених платіжних шлюзів для російських інтернет-магазинів. Надає REST API для прийому платежів банківськими картками з підтримкою 3-D Secure, холдирування та повернень.

Як працює інтеграція

Стандартний сценарій оплати:

1. Покупець вибирає оплату карткою, натискає «Оплатити»
2. Bitrix створює замовлення, викликає метод реєстрації замовлення в API Alfa-Bank
3. API повертає orderId та formUrl (URL платіжної форми)
4. Покупець перенаправляється на форму Alfa-Bank
5. Після оплати — редирект на returnUrl магазину
6. Alfa-Bank відправляє callback на failUrl/returnUrl або через окремий webhook
7. Bitrix перевіряє статус через API, підтверджує оплату

Підключення: що потрібно отримати від банку

• Логін та пароль до тестового та production шлюзу (або token замість логіну/пароля)
• URL шлюзу — тестовий (https://alfa.rbsuat.com/payment/rest/) та production (https://pay.alfabank.ru/payment/rest/)
• Доступ до особистого кабінету для моніторингу транзакцій

Реалізація обробника платіжної системи

Alfa-Bank підключається як платіжна система модуля sale. Структура файлів обробника в /local/php_interface/include/sale_payment/alfa_bank/:

handler.php        — клас обробника
.description.php   — метаданні
.settings.php      — налаштування: логін, пароль, URL шлюзу, режим (test/live)
template/          — шаблон кнопки

Клас обробника наслідується від \Bitrix\Sale\PaySystem\ServiceHandler. Ключові методи:

initiatePay — реєстрація замовлення та отримання URL форми:

public function initiatePay(\Bitrix\Sale\Payment $payment, \Bitrix\Main\Request $request = null)
{
    $order = $payment->getOrder();
    $sum   = $payment->getSum();

    $params = [
        'userName'   => $this->getBusinessValue($payment, 'ALFA_LOGIN'),
        'password'   => $this->getBusinessValue($payment, 'ALFA_PASSWORD'),
        'orderNumber'=> $order->getId(),
        'amount'     => (int)($sum * 100),   // у копійках
        'currency'   => 643,                 // RUB
        'returnUrl'  => $this->getReturnUrl($payment),
        'failUrl'    => $this->getReturnUrl($payment) . '?fail=1',
        'description'=> 'Оплата замовлення №' . $order->getId(),
    ];

    $response = $this->apiRequest('register.do', $params);

    if (!empty($response['errorCode']) && $response['errorCode'] !== '0') {
        return \Bitrix\Sale\PaySystem\ServiceResult::createError($response['errorMessage']);
    }

    // Зберегти orderId Alfa-Bank для подальшої перевірки
    $this->saveAlfaOrderId($payment, $response['orderId']);

    return \Bitrix\Sale\PaySystem\ServiceResult::createRedirect($response['formUrl']);
}

processRequest — обробка повернення покупця та перевірка статусу:

public function processRequest(\Bitrix\Sale\Payment $payment, \Bitrix\Main\Request $request)
{
    $alfaOrderId = $this->getAlfaOrderId($payment);
    if (!$alfaOrderId) {
        return \Bitrix\Sale\PaySystem\ServiceResult::createError('Alfa orderId not found');
    }

    $status = $this->apiRequest('getOrderStatus.do', [
        'userName' => $this->getBusinessValue($payment, 'ALFA_LOGIN'),
        'password' => $this->getBusinessValue($payment, 'ALFA_PASSWORD'),
        'orderId'  => $alfaOrderId,
    ]);

    // orderStatus: 2 = оплачено
    if (isset($status['orderStatus']) && $status['orderStatus'] == 2) {
        $payment->setPaid('Y');
        return \Bitrix\Sale\PaySystem\ServiceResult::create();
    }

    return \Bitrix\Sale\PaySystem\ServiceResult::createError('Payment not confirmed');
}

Двостадійні платежі (холдирування)

Alfa-Bank підтримує двостадійну схему: спочатку холдирування (registerPreAuth.do), потім підтвердження (deposit.do) або скасування (reverse.do). Для магазинів з оплатою після підтвердження наявності товару це правильна схема.

// Холдирування
$response = $this->apiRequest('registerPreAuth.do', $params);

// Підтвердження (при відправці товару)
$this->apiRequest('deposit.do', [
    'userName' => $login,
    'password' => $password,
    'orderId'  => $alfaOrderId,
    'amount'   => (int)($sum * 100),
]);

Повернення

API Alfa-Bank підтримує повне та часткове повернення через метод refund.do:

$this->apiRequest('refund.do', [
    'userName' => $login,
    'password' => $password,
    'orderId'  => $alfaOrderId,
    'amount'   => (int)($refundAmount * 100),  // часткове повернення
]);

Повернення ініціюється з коду Bitrix при скасуванні замовлення. Додайте обробник на подію OnSaleOrderCanceled:

AddEventHandler('sale', 'OnSaleOrderCanceled', function(\Bitrix\Main\Event $event) {
    $order = $event->getParameter('ENTITY');
    // Визначити платіж з потрібною платіжною системою, викликати refund.do
});

Фіскалізація (ФЗ-54)

Для інтернет-магазинів, зобов'язаних виставляти чеки, Alfa-Bank підтримує передачу даних чека у запиті реєстрації замовлення через параметр taxSystem та об'єкт orderBundle з позиціями замовлення. Позиції беруться з кошика Bitrix ($order->getBasket()), ставки ПДВ — з налаштувань каталогу.

Тестування

У тестовому середовищі Alfa-Bank використовуйте карту 4111111111111111, термін 12/26, будь-який CVV. Тест повинен включити повний цикл: реєстрація → форма → оплата → повернення на сайт → перевірка статусу → оновлення платежу в Bitrix.

Строки розробки