Интеграция 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
• Отклонение по лимиту
• Отмену на странице оплаты

Сроки