Интеграция 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();
}
Статусы платежа:
| Статус | Значение |
|---|---|
pending |
Создан, ожидает оплаты |
processing |
Обрабатывается |
succeeded |
Оплачен успешно |
failed |
Отклонён |
cancelled |
Отменён |
refunded |
Возвращён |
Специфика для Беларуси
БелВЭБ поддерживает оплату картами VISA, Mastercard и Белкарт. Для карт Белкарт 3DS-верификация работает через национальную систему аутентификации — важно тестировать именно этот сценарий отдельно. В наших проектах мы выделяем на это дополнительный день.
Валюта — BYN, сумма передаётся в рублях с двумя знаками после запятой (не в копейках, в отличие от некоторых других шлюзов). Это частый источник ошибок при переносе кода с других интеграций.
Что входит в нашу работу?
Мы делаем проект под ключ:
- разработка кастомного обработчика платёжной системы с OAuth, идемпотентностью и HMAC-верификацией;
- интеграция с кассой Битрикса (встроенная логика заказов);
- реализация 3DS-редиректа и обработка callback;
- настройка тестовой среды и кеширование токена;
- тестирование: создание платежа, возврат, частичный возврат, отмена;
- настройка логгирования ошибок и уведомлений;
- передача документации и доступов, обучение вашего администратора.
Сроки ориентировочно
| Задача | Срок |
|---|---|
| Разработка обработчика + авторизация OAuth | 2–3 дня |
| Тестирование полного цикла (оплата, возврат, webhook) | 1 день |
| Боевое подключение | 1 день |
Опыт нашей команды — 10+ лет интеграций с 1С-Битрикс, более 50 проектов по платёжным шлюзам. Закажите интеграцию — получите готовый модуль, который работает без сюрпризов.
Пример настроек тестовой среды
Для тестирования используйте test-api.belveb.by. Убедитесь, что в настройках платёжной системы Битрикса указан корректный URL. Кеш токена в тестовой среде лучше отключить, чтобы видеть каждый запрос. Всегда проверяйте подпись webhook даже в тесте — это обязательное требование безопасности.
Как выполнить частичный возврат?
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).
Пошаговая инструкция по интеграции (для разработчиков)
- Получите client_id и client_secret в личном кабинете БелВЭБ.
- Реализуйте класс
BelvebAuthдля получения и кеширования токена. - Создайте метод создания платежа с обязательным полем
X-Idempotency-Key. - Настройте обработку webhook с проверкой подписи HMAC.
- Реализуйте 3DS-редирект: перехватите ответ шлюза с полем
redirectUrl, перенаправьте клиента. - После успешного колбэка подтвердите платёж через capture (если двухстадийный).
- Протестируйте все сценарии: успех, отказ, возврат, частичный возврат.
Свяжитесь с нами для получения консультации по архитектуре интеграции. Мы пришлём готовый пример обработчика и смету за 4 часа.