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

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

Альфа-Банк эквайринг — один из распространённых платёжных шлюзов для российских интернет-магазинов. Предоставляет REST API для приёма платежей банковскими картами с поддержкой 3-D Secure, холдирования и возвратов.

Как работает интеграция

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

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

Подключение: что нужно получить от банка

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

Реализация обработчика платёжной системы

Альфа-Банк подключается как платёжная система модуля 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). Для магазинов с оплатой после подтверждения наличия товара это правильная схема.

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

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

Возвраты

API Альфа-Банка поддерживает полный и частичный возврат через метод refund.do:

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

Возврат инициируется из кода Битрикс при отмене заказа. Повесьте обработчик на событие OnSaleOrderCanceled:

AddEventHandler('sale', 'OnSaleOrderCanceled', function(\Bitrix\Main\Event $event) {
    $order = $event->getParameter('ENTITY');
    // Определить платёж с нужной платёжной системой, вызвать refund.do
});

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

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

Тестирование

В тестовой среде Альфа-Банка используйте карту 4111111111111111, срок 12/26, CVV любой. Тест должен включить полный цикл: регистрация → форма → оплата → возврат на сайт → проверка статуса → обновление платежа в Битрикс.

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