Інтеграція 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 години.