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

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

Халва — карта рассрочки Совкомбанка. Держатель карты оплачивает товар в рассрочку без процентов (магазин субсидирует их сам), а магазин получает полную сумму сразу. Для интернет-магазинов это инструмент увеличения среднего чека: клиент охотнее покупает дорогостоящий товар, когда видит разбивку «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 рабочих дней. Требуется прохождение проверки со стороны Совкомбанка.