Інтеграція 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, сума передається у рублях із двома знаками після коми (не у копійках, на відміну від деяких інших шлюзів). Це часте джерело помилок при перенесенні коду з інших інтеграцій.

Терміни