Інтеграція 1С-Бітрікс з платіжною системою Белкарт (Білорусь)

Інтеграція 1С-Бітрікс з платіжною системою Белкарт (Білорусь)

Белкарт — національна платіжна система Республіки Білорусь. Якщо інтернет-магазин працює на білоруському ринку та приймає лише VISA/Mastercard, він втрачає частину аудиторії: у значної частки білоруських покупців основною карткою є Белкарт або Белкарт-Маестро. Інтеграція Белкарт відрізняється від стандартного VISA/Mastercard-еквайрингу: картки обробляються через білоруський процесинговий центр (НКФО «ЄРВП»), і технічний протокол відрізняється.

Архітектура та протокол

Белкарт надає кілька способів інтеграції:

1. Через банк-еквайер — більшість білоруських банків (Беларусбанк, Пріорбанк, БелВЕБ, МТБанк та ін.) підтримують Белкарт у своєму еквайрингу. У цьому випадку Белкарт-транзакції обробляються через той самий шлюз, що й VISA/Mastercard, — окремої інтеграції не потрібно, лише перевірити у договорі.

2. Пряма інтеграція через НКФО «ЄРВП» — для великих торгових точок, підключення безпосередньо до Белкарт-процесингу. Протокол: ISO 8583 або REST API НКФО ЄРВП.

Для більшості інтернет-магазинів на Бітрікс актуальний перший варіант — додавання Белкарт до існуючого банківського еквайрингу.

Особливості протоколу Белкарт

При прямому підключенні через НКФО ЄРВП використовується REST API зі специфічними особливостями:

class BelkartGateway
{
    private const API_URL = 'https://gateway.belkart.by/api/v1/';
    private string $terminalId;
    private string $merchantKey;

    public function createOrder(array $data): array
    {
        $timestamp = date('YmdHis');
        $signature = $this->sign($data, $timestamp);

        $payload = [
            'TerminalID'  => $this->terminalId,
            'OrderID'     => 'BX' . $data['orderId'],
            'Amount'      => (int)($data['amount'] * 100), // копійки BYN
            'Currency'    => '933', // BYN
            'Description' => 'Оплата замовлення №' . $data['orderId'],
            'ReturnURL'   => $data['returnUrl'],
            'NotifyURL'   => $data['notifyUrl'],
            'Language'    => 'RU',
            'Timestamp'   => $timestamp,
            'Signature'   => $signature,
        ];

        return $this->request('orders', $payload);
    }

    private function sign(array $data, string $timestamp): string
    {
        // Конкатенація полів у визначеному порядку + ключ
        $signString = $this->terminalId
            . $data['orderId']
            . (int)($data['amount'] * 100)
            . '933'
            . $timestamp
            . $this->merchantKey;

        return strtoupper(hash('sha256', $signString));
    }

    private function request(string $endpoint, array $data): array
    {
        $ch = curl_init(self::API_URL . $endpoint);
        curl_setopt_array($ch, [
            CURLOPT_POST           => true,
            CURLOPT_POSTFIELDS     => json_encode($data),
            CURLOPT_RETURNTRANSFER => true,
            CURLOPT_HTTPHEADER     => ['Content-Type: application/json'],
        ]);
        $result = curl_exec($ch);
        curl_close($ch);
        return json_decode($result, true);
    }
}

3D-Secure для Белкарт

Белкарт підтримує протокол 3D-Secure (національна реалізація — «Белкарт-3D»). Після редиректу на сторінку оплати покупець проходить верифікацію через SMS-код або мобільний банк. Технічно це обробляється на стороні процесингу, магазин лише отримує підсумкове повідомлення — втручання у протокол 3DS не потрібно.

Спільна форма оплати (Multi-payment)

Рекомендований UX для білоруських магазинів — єдина форма з кількома платіжними системами:

[VISA / Mastercard] [Белкарт] [ЄРВП]

У 1С-Бітрікс це реалізується через кілька платіжних систем у модулі sale або через єдиний обробник із параметром paymentType. При виборі покупцем «Белкарт» — форма показує карткові поля з логотипом Белкарт; решта флоу ідентичний еквайрингу VISA.

Обробка повідомлень

$body = file_get_contents('php://input');
$data = json_decode($body, true);

// Верифікація підпису відповіді
$receivedSig = $data['Signature'] ?? '';
$expectedSig = strtoupper(hash('sha256',
    $data['TerminalID']
    . $data['OrderID']
    . $data['Amount']
    . $data['Currency']
    . $data['Status']
    . $merchantKey
));

if (!hash_equals($expectedSig, $receivedSig)) {
    http_response_code(403);
    exit;
}

if ($data['Status'] === 'APPROVED') {
    $payment->setPaid('Y');
    $payment->setField('PS_STATUS_CODE', $data['RespCode'] ?? '');
    $payment->save();
}

Тестування

Белкарт надає тестові картки через банки-учасники. Тестова картка видається при підключенні до тестового середовища шлюзу. Критично важливо протестувати:

• Успішну оплату карткою Белкарт із 3D-Secure
• Відхилення за лімітом
• Скасування на сторінці оплати

Терміни