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

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

БелВЭБ (Белорусский банк развития и реконструкции) предоставляет интернет-эквайринг для белорусских интернет-магазинов. Банк ориентирован на корпоративный сегмент, и его платёжный шлюз имеет ряд технических особенностей, которые отличают его от более распространённых решений. Интеграция с 1С-Битрикс требует разработки кастомного обработчика платёжной системы — готовых модулей на Маркетплейсе практически нет.

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

БелВЭБ предоставляет платёжный шлюз на базе технологии 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, уникальная на каждую попытку создания платежа. Обеспечивает идемпотентность: повторный запрос с тем же ключом вернёт тот же платёж без его дублирования.

Webhook-уведомления

БелВЭБ подписывает уведомления 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, сумма передаётся в рублях с двумя знаками после запятой (не в копейках, в отличие от некоторых других шлюзов). Это частый источник ошибок при переносе кода с других интеграций.

Сроки