שילוב תשלומים בהלוואה: API, ווידג'ט, Webhook

שילוב תוכנית התשלומים של Halva באתר שלך

בעל חנות מסחר אלקטרוני מאבד לקוחות בשלב התשלום — פריטים יקרים ננטשים עקב היעדר אפשרויות תשלומים. לדוגמה, חנות אלקטרוניקה שמה לב ש-40% מהעגלות הנטושות היו עבור פריטים בעלי ערך גבוה. לאחר הטמעת הווידג'ט של Halva, הנטישה הצטמצמה בחצי. הוספת תשלומים פותרת את הבעיה: הקונה משלם בחלקים, והחנות מקבלת את מלוא הסכום מיד. שילבנו את Halva עבור יותר מ-15 חנויות במשך מספר שנים, וההמרה עלתה בממוצע ב-30%.

כיצד פועל הווידג'ט של Halva

Halva הוא כרטיס אשראי של Sovcombank המציע תשלומים ללא ריבית. בעל הכרטיס משלם ללא ריבית, בעוד שהחנות מממנת את העמלה. עבור חנויות מקוונות, זהו כלי להגדלת ערך ההזמנה הממוצע: לקוחות נוטים יותר לקנות פריטים יקרים כשהם רואים פירוט כמו "4 תשלומים חודשיים". הווידג'ט מציג את התשלום החודשי על כרטיס המוצר. הוא נטען דינמית מבלי להאט את העמוד — ממוסגר ב-iframe, הוא אינו משפיע על LCP.

איך זה עובד

האינטגרציה מתבצעת דרך API של Halva או ווידג'ט שותף. הזרימה הבסיסית:

1. הקונה בוחר "שלם בתשלומים עם Halva"
2. החנות יוצרת הזמנה דרך API ומקבלת קישור
3. הקונה מאשר במערכת Halva ומאשר את התשלומים
4. Halva מודיעה לחנות על האישור
5. החנות שולחת את הסחורה

אינטגרציית API

יש צורך בחוזה עם Sovcombank. לאחר מכן, תקבל 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'); // ссылка на страницу Халвы
    }
}

ווידג'ט להצגת תשלומים על כרטיס המוצר

Halva מספקת ווידג'ט JavaScript להצגת התשלום החודשי ישירות בעמוד המוצר:

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

הווידג'ט מחשב ומציג אוטומטית תשלום חודשי ליד המחיר. אם קיימות מספר אפשרויות תשלום, הוא מציג את התשלום המינימלי. לפי הסטטיסטיקות שלנו, הווידג'ט מכפיל את ההמרה בהשוואה להצעות טקסט פשוטות.

כיצד לאבטח Webhook מפני זיוף

ה-Webhook מודיע לחנות על שינויי סטטוס הזמנה — APPROVED, REJECTED או CANCELLED. בלעדיו, לא תדע אם התשלום עבר. חתימת HMAC-SHA256 מונעת זיוף: ודא אותה בצד שלך. החתימה מחושבת מגוף הבקשה ומפתח סודי. השווה עם כותרת 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'); // ссылка на страницу Халвы } } . אם היא לא תואמת, דחה את הבקשה.

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 חודשים), שנקבעים בחוזה עם Sovcombank. בדוק את התנאי דרך API:

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

הצג רק תנאים זמינים לקונה בתפריט נפתח.

עמלה וסבסוד

החנות משלמת עמלה ל-Sovcombank עבור כל תשלום — אחוז מהסכום, בהתאם לתנאי. תנאים ארוכים יותר משמעם עמלה גבוהה יותר. יש לקחת זאת בחשבון בכלכלת העסק: או לכלול זאת במחיר או להתייחס לזה כעלות שיווקית להמרה גבוהה יותר. העמלה הממוצעת היא 5% לתקופה של 6 חודשים, אך יכולה לנוע בין 3% ל-8%.

טעויות אינטגרציה נפוצות

• דילוג על אימות חתימת HMAC ב-Webhook — תוקף יכול לזייף הודעות ולסמן הזמנות כמשולמות.
• שימוש בטוקן בדיקות בייצור — כל הבקשות הולכות לסביבת sandbox.
• אי טיפול בסטטוס CANCELLED — הזמנות נשארות תקועות כ"ממתינות לתשלום".
• העברת סכום שגוי לווידג'ט (ללא הנחות) — הקונה רואה תשלום אחד אבל תשלום אחר בקופה.

מה כלול בעבודה שלנו

• הכנה והגשת מסמכים ל-Sovcombank
• הגדרת ווידג'ט על כרטיסי מוצר
• הטמעת נקודות קצה של API (יצירת הזמנה, בדיקת סטטוס)
• טיפול ב-Webhook עם אימות חתימה
• בדיקת כל התרחישים (הצלחה, דחייה, ביטול)
• מתן תיעוד למפתחים שלך
• הדרכת צוות לעבודה עם דוחות
• תמיכה למשך 14 ימים לאחר ההשקה

החיבור לתוכנית Halva אורך 5 עד 10 ימי עסקים. הוא דורש מעבר אימות עם Sovcombank. צור קשר — נעזור לך לעבור את השלב הזה מהר יותר. קבל ייעוץ לפרויקט שלך היום. אנו מבטיחים אינטגרציה נכונה ותמיכה בכל השלבים. הניסיון שלנו: למעלה מ-5 שנים בשוק ויותר מ-30 פרויקטים שהושלמו.