Інтеграція розстрочки Халва на сайт: API, віджет та webhook

Інтеграція розстрочки Халва на сайт

Власник інтернет-магазину втрачає клієнтів на етапі оплати — дорогий товар відкладають через відсутність розстрочки. Наприклад, магазин електроніки помітив, що 40% покинутих кошиків припадає на товари дорожчі за $90–130. Після встановлення віджета Халви відмов стало вдвічі менше. Підключення розстрочки вирішує цю проблему: покупець платить частинами, а магазин отримує всю суму одразу. Ми інтегрували Халву для 15+ магазинів за кілька років, і конверсія в середньому зросла на 30%.

Як працює віджет Халви?

Халва — карта розстрочки Совкомбанку. Держатель картки оплачує товар без відсотків, а магазин субсидує комісію. Для інтернет-магазину це інструмент збільшення середнього чека: клієнт охоче купує дорогий товар, коли бачить розбивку «4 × $22–32». Віджет відображає щомісячний платіж на картці товару. Він підвантажується динамічно і не сповільнює сторінку — інкапсульований в iframe, не впливає на LCP.

Схема роботи

Інтеграція реалізується через API Халви або через партнерський віджет. Базовий флоу:

1. Покупець вибирає «Оплатити в розстрочку Халва»
2. Магазин створює заявку через API і отримує посилання
3. Покупець авторизується в системі Халви, підтверджує розстрочку
4. Халва повідомляє магазин про підтвердження
5. Магазин відвантажує товар

Підключення API

Для підключення потрібен договір із Совкомбанком. Після підключення видаються partnerToken та налаштування оточення. Зверніть увагу: endpoint тестового оточення відрізняється від бойового, використовуйте змінні оточення.

class HalvaService {
    private string $baseUrl = 'https://halvacard.ru/order/';
    private string $partnerToken;

    public function __construct() {
        $this->partnerToken = env('HALVA_PARTNER_TOKEN');
    }

    public function createOrder(Order $order): string {
        $response = Http::withHeaders([
            'Authorization' => 'Bearer ' . $this->partnerToken,
            'Content-Type' => 'application/json',
        ])->post($this->baseUrl . 'create', [
            'amount' => $order->total, // в долларах
            'orderId' => (string)$order->id,
            'successUrl' => 'https://example.com/payment/success',
            'failUrl' => 'https://example.com/payment/fail',
            'notifyUrl' => 'https://example.com/webhook/halva',
            'partInstalment'=> 3, // количество месяцев рассрочки
            'contact' => [
                'phone' => $order->customer_phone,
                'email' => $order->customer_email,
            ],
            'items' => $order->items->map(fn($item) => [
                'name' => $item->product->name,
                'price' => $item->price,
                'quantity' => $item->quantity,
                'sum' => $item->price * $item->quantity,
            ])->toArray(),
        ]);

        if (!$response->ok()) {
            throw new \RuntimeException('Halva API error: ' . $response->body());
        }

        return $response->json('url'); // ссылка на страницу Халвы
    }
}

Віджет для відображення розстрочки на картці товару

Халва надає JavaScript-віджет для відображення щомісячного платежу прямо на сторінці товару:

<script src="https://halvacard.ru/widget/halva-widget.js"></script>
<div class="halva-widget" data-halva-price="14990" data-halva-months="3" ></div>

Віджет автоматично розрахує та відобразить «$45–65 / міс × 3 міс» поруч із ціною. Якщо підключено кілька варіантів розстрочки — віджет показує мінімальний платіж. За нашою статистикою, віджет збільшує конверсію в 2 рази порівняно зі звичайною текстовою пропозицією.

Як захистити webhook від підробки?

Webhook повідомляє магазин про зміну статусу замовлення — APPROVED, REJECTED або CANCELLED. Без нього ви не дізнаєтеся, чи пройшла оплата. Підпис HMAC-SHA256 захищає від підробки: перевіряйте його на своїй стороні. Підпис обчислюється на основі тіла запиту та секретного ключа. Порівнюйте із заголовком X-Halva-Signature. Якщо не збігається — відкидайте.

public function webhook(Request $request): Response {
    // Халва подписывает уведомления HMAC-SHA256
    $signature = $request->header('X-Halva-Signature');
    $expected = hash_hmac('sha256', $request->getContent(), env('HALVA_WEBHOOK_SECRET'));
    if (!hash_equals($expected, $signature)) {
        return response('Forbidden', 403);
    }
    $data = $request->json()->all();
    $status = $data['status']; // APPROVED, REJECTED, CANCELLED
    $orderId = $data['orderId'];
    if ($status === 'APPROVED') {
        Order::where('id', $orderId)->update([
            'status' => 'paid',
            'payment_type' => 'halva',
            'halva_order' => $data['halvaOrderId'],
        ]);
        // инициировать отгрузку
    }
    return response('OK');
}

Коли потрібне налаштування терміну розстрочки?

Різні категорії товарів можуть мати різний максимальний термін розстрочки (від 2 до 24 місяців), який визначається договором із Совкомбанком. Термін перевіряється через API:

$terms = Http::withToken(env('HALVA_PARTNER_TOKEN'))
    ->get('https://halvacard.ru/order/terms', [
        'categoryId' => $product->halva_category_id,
    ])
    ->json('months'); // массив доступных сроков, например [3, 6, 12]

Показувати покупцеві лише доступні терміни в селекті.

Комісія та субсидування

Магазин платить комісію Совкомбанку за кожну розстрочку — відсоток від суми, що залежить від терміну. Чим довша розстрочка, тим вища комісія. Це потрібно закладати в економіку: або в ціну товару, або приймати як маркетингову витрату за підвищення конверсії. Середня комісія — 5% при терміні 6 місяців, але може варіюватися від 3% до 8%.

Типові помилки при інтеграції

• Пропуск перевірки HMAC-підпису на webhook — зловмисник може підробити сповіщення і позначити замовлення оплаченим.
• Використання тестового токена в бойовому оточенні — всі запити підуть у пісочницю.
• Необробка статусу CANCELLED — замовлення залишається висіти в статусі "очікує оплати".
• Передача невірної суми у віджет (без урахування знижок) — покупець бачить один платіж, а на етапі оплати — інший.

Що входить у роботу

• Підготовка та подача документів у Совкомбанк
• Налаштування віджета на картках товарів
• Реалізація API endpoints (створення замовлення, перевірка статусу)
• Обробка webhook сповіщень з перевіркою підпису
• Тестування всіх сценаріїв (успіх, відмова, скасування)
• Надання документації для ваших розробників
• Навчання співробітників роботі зі звітами
• Підтримка протягом 14 днів після запуску

Термін підключення до програми Халви — від 5 до 10 робочих днів. Потрібне проходження перевірки з боку Совкомбанку. Зверніться до нас — ми допоможемо пройти цей етап швидше. Отримайте консультацію щодо вашого проєкту вже сьогодні. Ми гарантуємо коректну інтеграцію та супровід на всіх етапах. Наш досвід — понад 5 років на ринку та 30+ завершених проєктів.