Halva Installment Payment Integration

Halva Installment Integration

Halva is Sovkombank installment card. Cardholder pays for goods in installments interest-free (store subsidizes interest), and store gets full amount immediately. For online stores this is tool increasing average check: customer more willing to buy expensive item when sees breakdown "4 × 2500 ₽".

How It Works

Integration realized via Halva API or partner widget. Basic flow:

1. Customer selects "Pay in Halva installment"
2. Store creates request via API and gets link
3. Customer authorizes in Halva system, confirms installment
4. Halva notifies store of confirmation
5. Store ships goods

API Connection

Contract with Sovkombank needed for connection. After connection partnerToken and environment settings issued.

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,          // in rubles
            'orderId'       => (string)$order->id,
            'successUrl'    => 'https://example.com/payment/success',
            'failUrl'       => 'https://example.com/payment/fail',
            'notifyUrl'     => 'https://example.com/webhook/halva',
            'partInstalment'=> 3, // number of installment months
            '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'); // link to Halva page
    }
}

Widget for Product Card Display

Halva provides JavaScript-widget for displaying monthly payment directly on product page:

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

Widget automatically calculates and displays "4 990 ₽ / month × 3 months" next to price. If multiple installment options connected — widget shows minimum payment.

Webhook Notification

public function webhook(Request $request): Response
{
    // Halva signs notifications with 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'],
        ]);
        // initiate shipment
    }

    return response('OK');
}

Displaying Installment Term

Different product categories may have different max installment term (2 to 24 months), determined by Sovkombank contract. Term checked via API:

$terms = Http::withToken(env('HALVA_PARTNER_TOKEN'))
    ->get('https://halvacard.ru/order/terms', [
        'categoryId' => $product->halva_category_id,
    ])->json('months'); // array of available terms, e.g. [3, 6, 12]

Show customer only available terms in select.

Commission and Subsidization

Store pays commission to Sovkombank for each installment — percentage of sum, depending on term. Longer installment — higher commission. This needs to be factored in economics: either into product price, or take as marketing expense for conversion increase.

Halva program connection period — 5 to 10 business days. Sovkombank verification passing required.