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

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

Альфа-Банк Беларусь — один из технологически продвинутых банков на белорусском рынке, предоставляет интернет-эквайринг на базе собственного платёжного шлюза. В отличие от российского Альфа-Банка, белорусская «дочка» использует другой API — основанный на протоколе OpenWay, что означает отдельную документацию и отдельный процесс подключения.

Технический стек шлюза

Альфа-Банк Беларусь использует платёжный шлюз на базе процессинга OpenWay (ecom.alfa-bank.by). Схема работы — стандартный redirect-flow:

1. Магазин отправляет запрос на регистрацию заказа → получает formUrl и orderId
2. Покупатель редиректируется на formUrl
3. После оплаты — редирект на returnUrl + уведомление на callbackUrl
4. Магазин проверяет статус через getOrderStatus

API принимает запросы через HTTPS, аутентификация — userName/password в параметрах запроса (basic-параметры, не заголовок). Формат — form-urlencoded или JSON в зависимости от endpoint.

Регистрация заказа

class AlfaBankBelarusGateway
{
    private const API_URL = 'https://ecom.alfa-bank.by/payment/rest/';
    private string $userName;
    private string $password;

    public function registerOrder(array $orderData): array
    {
        $params = [
            'userName'    => $this->userName,
            'password'    => $this->password,
            'orderNumber' => $orderData['number'],
            'amount'      => (int)($orderData['amount'] * 100), // копейки
            'currency'    => 933,  // BYN по ISO 4217
            'returnUrl'   => $orderData['returnUrl'],
            'failUrl'     => $orderData['failUrl'],
            'description' => 'Заказ №' . $orderData['number'],
            'language'    => 'ru',
            'pageView'    => 'DESKTOP', // или MOBILE
        ];

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

        if (!empty($response['errorCode']) && $response['errorCode'] !== '0') {
            throw new \RuntimeException(
                'Ошибка регистрации: ' . ($response['errorMessage'] ?? 'неизвестная ошибка')
            );
        }

        return $response; // содержит orderId и formUrl
    }

    private function request(string $method, array $params): array
    {
        $ch = curl_init(self::API_URL . $method);
        curl_setopt_array($ch, [
            CURLOPT_POST           => true,
            CURLOPT_POSTFIELDS     => http_build_query($params),
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_SSL_VERIFYPEER => true,
            CURLOPT_TIMEOUT        => 30,
        ]);
        $result = curl_exec($ch);
        curl_close($ch);
        return json_decode($result, true);
    }
}

Проверка статуса заказа

public function getOrderStatus(string $orderId): array
{
    return $this->request('getOrderStatus.do', [
        'userName' => $this->userName,
        'password' => $this->password,
        'orderId'  => $orderId,
        'language' => 'ru',
    ]);
}

Коды статусов аналогичны другим шлюзам на базе схожих процессинговых систем:

Интеграция в платёжную систему Битрикс

// /local/php_interface/include/sale_payment/alfabank_by/handler.php
class AlfaBankByHandler extends \Bitrix\Sale\PaySystem\ServiceHandler
{
    public function initiatePay(
        \Bitrix\Sale\Payment $payment,
        \Bitrix\Main\Request $request
    ): \Bitrix\Sale\PaySystem\ServiceResult {

        $result = new \Bitrix\Sale\PaySystem\ServiceResult();
        $order  = $payment->getOrder();

        $gateway = new AlfaBankBelarusGateway(
            $this->getBusinessValue($payment, 'ALFABANK_BY_USER'),
            $this->getBusinessValue($payment, 'ALFABANK_BY_PASSWORD')
        );

        try {
            $response = $gateway->registerOrder([
                'number'    => 'BX' . $order->getId(),
                'amount'    => $payment->getSum(),
                'returnUrl' => $this->getSuccessUrl($payment),
                'failUrl'   => $this->getFailUrl($payment),
            ]);

            // Сохраняем orderId банка для последующей проверки
            $payment->setField('PS_INVOICE_ID', $response['orderId']);
            $payment->save();

            $result->setPaymentUrl($response['formUrl']);
        } catch (\Exception $e) {
            $result->addError(new \Bitrix\Main\Error($e->getMessage()));
        }

        return $result;
    }
}

Обработка callback-уведомлений

Альфа-Банк Беларусь отправляет GET-запрос на callbackUrl (или POST, в зависимости от настроек договора). Параметры включают mdOrder (orderId банка) и orderNumber (номер заказа магазина).

Важно: не обновлять статус только на основании callback-параметров. Всегда вызывать getOrderStatus.do для верификации:

public function processRequest(
    \Bitrix\Sale\Payment $payment,
    \Bitrix\Main\Request $request
): \Bitrix\Sale\PaySystem\ServiceResult {

    $result = new \Bitrix\Sale\PaySystem\ServiceResult();
    $orderId = $request->get('mdOrder') ?: $payment->getField('PS_INVOICE_ID');

    $gateway = new AlfaBankBelarusGateway(/* credentials */);
    $status = $gateway->getOrderStatus($orderId);

    if (($status['OrderStatus'] ?? -1) === 2) {
        $payment->setPaid('Y');
        $payment->save();
        $result->setOperationType(\Bitrix\Sale\PaySystem\ServiceResult::MONEY_COMING);
    }

    return $result;
}

Валюта и суммы

• Валюта BYN — ISO код 933
• Сумма в белорусских копейках (целое число)
• Если на сайте используется другая валюта — конвертация до создания платежа на стороне магазина

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

Альфа-Банк Беларусь предоставляет тестовую среду (ecom-test.alfa-bank.by). Тестовые данные выдаются персонально при подключении. Минимальный сценарий проверки: успешная оплата → callback → статус 2 → запись в Битрикс → повторная оплата по тому же orderNumber должна возвращать ошибку «заказ уже оплачен».

Сроки