Інтеграція 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 має повертати помилку «замовлення вже оплачено».

Терміни