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

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

Халва — карта рассрочки Совкомбанку. Власник карти оплачує товар у рассрочку без відсотків (магазин субсидирує їх сам), а магазин отримує повну суму відразу. Для інтернет-магазинів це інструмент збільшення середнього чека: клієнт охочіше купує дорогий товар, коли бачить розбивку «4 × 2500 ₽».

Схема роботи

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

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

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

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

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>

Віджет автоматично розраховує та відображає «4 990 ₽ / мес × 3 мес» рядом з ціною. Якщо підключено кілька варіантів рассрочки — віджет показує мінімальний платіж.

Webhook сповіщення

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 до 10 робочих днів. Потребна прохідження перевірки зі сторони Совкомбанку.