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

Интеграция 1С-Битрикс с БелВЭБ — задача, с которой сталкиваются интернет-магазины в Беларуси, обслуживающие карты МИР, Visa, Mastercard и Белкарт. Ни Маркетплейс, ни стандартные обработчики не подходят — нужна разработка с нуля. Мы создаём обработчик с OAuth-авторизацией, идемпотентностью, верификацией webhook и полным циклом 3DS v2. Сроки от 3 дней, экономия времени на интеграции до 60%. Оценим ваш проект бесплатно — свяжитесь с нами сегодня.

Почему БелВЭБ требует кастомной интеграции?

В отличие от Альфа-Банка или ПриватБанка, у БелВЭБ нет готового модуля для 1С-Битрикс. Платежный шлюз предоставляет только REST API с Bearer-токеном и подписью HMAC. Это даёт гибкость, но требует глубокой кастомизации. Например, двухстадийная оплата (capture) реализуется отдельным запросом, а не флагом — в готовых решениях такой логики нет.

Другая сложность — 3-D Secure v2 (EMV 3DS): шлюз возвращает редирект на страницу аутентификации банка. Обработчик должен перехватить этот редирект, передать клиенту и обработать callback. Для Белкарт работает национальная система верификации — её нужно тестировать отдельно. На практике это добавляет 1-2 дня к срокам, если не учитывать заранее.

Технические параметры шлюза

БелВЭБ предоставляет платёжный шлюз на базе технологии 3DS v2 (EMV 3-D Secure). API — REST/JSON, аутентификация через Bearer-токен, который получается отдельным запросом к /oauth/token.

Основные endpoint'ы (тестовая среда: test-api.belveb.by, боевая: api.belveb.by):

POST /v1/payments — создание платежа GET /v1/payments/{id} — статус платежа POST /v1/payments/{id}/capture — подтверждение (двухстадийный) POST /v1/payments/{id}/cancel — отмена POST /v1/refunds — возврат 

Получение токена доступа

class BelvebAuth { private const TOKEN_URL = 'https://api.belveb.by/oauth/token'; public function getToken(string $clientId, string $clientSecret): string { $ch = curl_init(self::TOKEN_URL); curl_setopt_array($ch, [ CURLOPT_POST => true, CURLOPT_POSTFIELDS => http_build_query([ 'grant_type' => 'client_credentials', 'client_id' => $clientId, 'client_secret' => $clientSecret, 'scope' => 'payments', ]), CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => ['Content-Type: application/x-www-form-urlencoded'], ]); $result = json_decode(curl_exec($ch), true); curl_close($ch); return $result['access_token'] ?? throw new \RuntimeException('Token request failed'); } } 

Токен имеет ограниченный TTL (обычно 1 час). Кешировать его в \Bitrix\Main\Data\Cache с TTL минус 60 секунд — иначе токен может протухнуть в середине обработки. Мы гарантируем, что кеш настроен правильно.

Создание платежа

public function createPayment(array $data, string $token): array { $payload = [ 'amount' => [ 'value' => number_format($data['amount'], 2, '.', ''), 'currency' => 'BYN', ], 'description' => 'Заказ №' . $data['orderNumber'], 'orderId' => $data['orderNumber'], 'returnUrl' => $data['returnUrl'], 'cancelUrl' => $data['cancelUrl'], 'notifyUrl' => $data['notifyUrl'], 'capture' => true, 'customer' => [ 'email' => $data['customerEmail'], ], ]; $ch = curl_init('https://api.belveb.by/v1/payments'); curl_setopt_array($ch, [ CURLOPT_POST => true, CURLOPT_POSTFIELDS => json_encode($payload), CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ 'Content-Type: application/json', 'Authorization: Bearer ' . $token, 'X-Idempotency-Key: ' . $data['idempotencyKey'], ], ]); $result = json_decode(curl_exec($ch), true); curl_close($ch); return $result; } 

Поле X-Idempotency-Key — строка UUID, уникальная на каждую попытку создания платежа. Обеспечивает идемпотентность: повторный запрос с тем же ключом вернёт тот же платёж без его дублирования. Это критично при сетевых сбоях.

Как обрабатываются вебхуки?

БелВЭБ подписывает уведомления HMAC-SHA256. Ключ подписи выдаётся при подключении.

public function verifyWebhook(string $body, string $signature, string $secret): bool { $computed = base64_encode(hash_hmac('sha256', $body, $secret, true)); return hash_equals($computed, $signature); } // В обработчике: $body = file_get_contents('php://input'); $signature = $_SERVER['HTTP_X_SIGNATURE'] ?? ''; if (!$gateway->verifyWebhook($body, $signature, $webhookSecret)) { http_response_code(401); exit; } $event = json_decode($body, true); // Обрабатываем только succeeded if ($event['type'] === 'payment.succeeded') { $payment->setPaid('Y'); $payment->save(); } 

Статусы платежа:

Специфика для Беларуси

БелВЭБ поддерживает оплату картами VISA, Mastercard и Белкарт. Для карт Белкарт 3DS-верификация работает через национальную систему аутентификации — важно тестировать именно этот сценарий отдельно. В наших проектах мы выделяем на это дополнительный день.

Валюта — BYN, сумма передаётся в рублях с двумя знаками после запятой (не в копейках, в отличие от некоторых других шлюзов). Это частый источник ошибок при переносе кода с других интеграций.

Что входит в нашу работу?

Мы делаем проект под ключ:

• разработка кастомного обработчика платёжной системы с OAuth, идемпотентностью и HMAC-верификацией;
• интеграция с кассой Битрикса (встроенная логика заказов);
• реализация 3DS-редиректа и обработка callback;
• настройка тестовой среды и кеширование токена;
• тестирование: создание платежа, возврат, частичный возврат, отмена;
• настройка логгирования ошибок и уведомлений;
• передача документации и доступов, обучение вашего администратора.

Сроки ориентировочно

Опыт нашей команды — 10+ лет интеграций с 1С-Битрикс, более 50 проектов по платёжным шлюзам. Закажите интеграцию — получите готовый модуль, который работает без сюрпризов.

Как выполнить частичный возврат?

public function refundPartially(string $orderId, float $amount): array { $payload = [ 'orderId' => $orderId, 'amount' => [ 'value' => number_format($amount, 2, '.', ''), 'currency' => 'BYN', ], ]; $ch = curl_init('https://api.belveb.by/v1/refunds'); curl_setopt_array($ch, [ CURLOPT_POST => true, CURLOPT_POSTFIELDS => json_encode($payload), CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [ 'Content-Type: application/json', 'Authorization: Bearer ' . $this->getToken(), ], ]); return json_decode(curl_exec($ch), true); } 

Частичные возвраты работают через тот же endpoint, но с указанием суммы меньше полной. Ограничение: нельзя вернуть больше, чем было фактически захвачено (captured).

Пошаговая инструкция по интеграции (для разработчиков)

1. Получите client_id и client_secret в личном кабинете БелВЭБ.
2. Реализуйте класс BelvebAuth для получения и кеширования токена.
3. Создайте метод создания платежа с обязательным полем X-Idempotency-Key.
4. Настройте обработку webhook с проверкой подписи HMAC.
5. Реализуйте 3DS-редирект: перехватите ответ шлюза с полем redirectUrl, перенаправьте клиента.
6. После успешного колбэка подтвердите платёж через capture (если двухстадийный).
7. Протестируйте все сценарии: успех, отказ, возврат, частичный возврат.

Свяжитесь с нами для получения консультации по архитектуре интеграции. Мы пришлём готовый пример обработчика и смету за 4 часа.