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