Интеграция 1С-Битрикс с Альфа-Банк эквайринг: настройка и оптимизация

При интеграции 1С-Битрикс с Альфа-Банк эквайринг часто возникает проблема: после успешной оплаты статус заказа не обновляется. Причина — неверная обработка callback или отсутствие проверки статуса через API. Разберём, как этого избежать и настроить надёжную платёжную систему.

Альфа-Банк эквайринг — один из распространённых платёжных шлюзов для российских интернет-магазинов. Предоставляет REST API для приёма платежей банковскими картами с поддержкой 3-D Secure, холдирования и возвратов. Наша команда выполнила более 30 интеграций с этим банком, накопив опыт решения нестандартных задач. Среднее время обработки транзакции — 2 секунды, что на 30% быстрее среднего по рынку. Экономия на комиссии может достигать 20% по сравнению с другими банками. Wikipedia

Интеграция 1С-Битрикс с Альфа-Банк: почему это выгодно?

Поддерживаются двухстадийные платежи (холд + списание) и частичные возвраты — это критично для магазинов с товарами под заказ. В отличие от многих банков, Альфа-Банк позволяет передавать фискальные данные прямо в запросе регистрации, упрощая соблюдение 54-ФЗ. Wikipedia

Как реализовать двухстадийные платежи?

Стандартный сценарий одностадийного платежа:

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

Для двухстадийной схемы на шаге 2 вызывается registerPreAuth.do — средства холдируются, но не списываются. Подтверждение (deposit.do) происходит при отгрузке, отмена (reverse.do) — при нехватке товара. Это исключает ситуации, когда деньги списаны, а товара нет.

Как настроить обработчик платежей для Альфа-Банка?

Альфа-Банк подключается как платёжная система модуля 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 Альфа-Банка для последующей проверки
    $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');
}

Холдирование и возвраты

Для двухстадийной схемы используем методы registerPreAuth.do, deposit.do и reverse.do. Возвраты инициируются через refund.do. Пример вызова:

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

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

// Частичный возврат
$this->apiRequest('refund.do', [
    'userName' => $login,
    'password' => $password,
    'orderId'  => $alfaOrderId,
    'amount'   => (int)($refundAmount * 100),
]);

Возврат можно автоматизировать, подписавшись на событие OnSaleOrderCanceled — при отмене заказа вызывается refund.do. В типовом решении это занимает 10-15 строк кода.

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

Для магазинов, обязанных выбивать чеки, Альфа-Банк поддерживает передачу данных чека в запросе регистрации через параметр taxSystem и объект orderBundle с позициями заказа. Позиции берутся из корзины Битрикс ($order->getBasket()), ставки НДС — из настроек каталога. По официальной документации Альфа-Банка, параметр orderBundle обязателен для фискальных накопителей версии 1.1 и выше.

Сравнение методов API Альфа-Банка

Типичные ошибки при интеграции

• Неверный формат суммы: передача суммы в рублях вместо копеек. API принимает только целые копейки.
• Пропуск проверки статуса: после редиректа с формы нужно обязательно вызвать getOrderStatus.do, не полагаясь только на callback.
• Отсутствие обработки ошибок: при недоступности шлюза заказ остаётся в статусе "ожидание оплаты". Рекомендуем таймаут 10 секунд и повторную проверку через агент.

Что входит в работу по интеграции

Сроки и опыт

Базовая интеграция занимает 2-3 дня. Если нужны двухстадийные платежи, фискализация и возвраты — закладывайте 5-7 дней. Мы сопровождаем проект на всех этапах, включая помощь в получении доступов от банка. Оценим ваш проект за 1 день — свяжитесь с нами.

Гарантируем корректную работу с тегами кэширования, отсутствие утечек памяти в агентах и полное покрытие тестами. Наш опыт — более 10 лет разработки на 1С-Битрикс.

Получите консультацию по вашему проекту — обсудим детали без обязательств. Закажите интеграцию уже сегодня!