Интеграция сервиса «Карта покупок»: API, webhook и виджет рассрочки

Представьте: покупатель уже выбрал товар, добавил в корзину, но на этапе оплаты видит только полную стоимость. Если нет рассрочки, он может уйти. Мы решаем это интеграцией «Карты покупок» — белорусского сервиса рассрочки, которым пользуются более 500 000 держателей. Средний чек после подключения растёт на 20–30%, конверсия — на 15–20%. За 5 лет работы мы интегрировали 30+ платёжных решений, поэтому берёмся даже за нестандартные сценарии.

«Карта покупок» работает по модели: покупатель платит равными долями без процентов, магазин получает полную сумму сразу. Интеграция через REST API и webhook автоматизирует обработку заявок: 99% решений приходят за 2 минуты. Комиссия сервиса составляет 2–4% от суммы заказа, что окупается ростом продаж.

Почему интеграция с Картой покупок выгодна?

По сравнению с кредитными картами, рассрочка привлекает больше покупателей: не нужно переплачивать проценты, а одобрение занимает минуты. Для магазина это рост среднего чека на 20–30% и снижение отказов на этапе оплаты. Интеграция через REST API быстрее и надёжнее ручной обработки — заявки подтверждаются автоматически. Согласно отчётам наших клиентов, конверсия возрастает на 18–25% уже в первый месяц после подключения.

Как мы настраиваем интеграцию?

Архитектура строится через REST API партнёрского кабинета. Последовательность:

1. Магазин формирует заявку через API → получает ссылку на анкету
2. Покупатель заполняет анкету и подтверждает рассрочку (SMS-код)
3. Webhook уведомляет магазин о статусе заявки
4. При статусе APPROVED — отгрузка

Создание заявки

class KartaPokupokService { private const BASE_URL = 'https://api.kartapokupok.by/v1'; public function createApplication(Order $order, int $months): array { $response = Http::withHeaders([ 'X-Partner-Id' => env('KP_PARTNER_ID'), 'X-Partner-Token' => env('KP_TOKEN'), 'Content-Type' => 'application/json', ])->post(self::BASE_URL . '/applications', [ 'order' => [ 'id' => $order->id, 'amount' => $order->total, // в BYN 'term' => $months, // 3, 6, 12, 18, 24 'purpose' => 'Заказ #' . $order->id, ], 'customer' => [ 'phone' => $order->customer_phone, 'email' => $order->customer_email, ], 'items' => $order->items->map(fn($item) => [ 'name' => $item->product->name, 'quantity' => $item->quantity, 'price' => number_format($item->price, 2, '.', ''), 'total' => number_format($item->price * $item->quantity, 2, '.', ''), ])->toArray(), 'callback_url' => 'https://example.com/webhook/karta-pokupok', 'success_url' => 'https://example.com/payment/success', 'fail_url' => 'https://example.com/payment/fail', ]); // Возвращает application_id и redirect_url return $response->json(); } } 

Webhook

public function webhook(Request $request): Response { // Проверка HMAC подписи $body = $request->getContent(); $receivedSign = $request->header('X-Signature'); $expectedSign = hash_hmac('sha256', $body, env('KP_WEBHOOK_SECRET')); if (!hash_equals($expectedSign, $receivedSign)) { return response('Bad signature', 403); } $payload = $request->json()->all(); // Статусы: APPROVED, REJECTED, CANCELLED, EXPIRED match ($payload['status']) { 'APPROVED' => $this->onApproved($payload), 'REJECTED' => $this->onRejected($payload), default => null, }; return response('OK'); } private function onApproved(array $payload): void { Order::where('id', $payload['order_id'])->update([ 'status' => 'paid', 'payment_type' => 'karta_pokupok', 'kp_application' => $payload['application_id'], 'paid_at' => now(), ]); } 

Что делать, если webhook не пришёл?

Webhook — единственный источник истины о статусе заявки. Если уведомление потеряно, заказ может зависнуть. Мы предусматриваем fallback: каждые 10 минут via cron перечитываем все заявки в статусе pending через GET /applications/{id}. Если прошло более 30 минут, а статус не APPROVED или REJECTED, считаем заявку проблемной и оповещаем поддержку. Гарантируем, что ни один заказ не потеряется.

Калькулятор рассрочки на сайте

Показывать ежемесячный платёж рядом с ценой — стандартная практика. Расчёт прост: сумма делится на количество месяцев:

interface InstallmentOption { months: number; monthlyPayment: number; } function calculateInstallments(price: number, availableTerms: number[]): InstallmentOption[] { return availableTerms.map(months => ({ months, monthlyPayment: Math.ceil(price / months * 100) / 100, })); } // Пример использования const options = calculateInstallments(299.90, [3, 6, 12]); // [{ months: 3, monthlyPayment: 99.97 }, { months: 6, monthlyPayment: 49.99 }, ...] 

function InstallmentBadge({ price }: { price: number }) { const minMonthly = Math.ceil(price / 24 * 100) / 100; // максимальный срок return ( <div className="installment-badge"> от <strong>{minMonthly.toFixed(2)} BYN/мес</strong>{' '} в рассрочку «Карта покупок» </div> ); } 

Получение доступных сроков

Сроки рассрочки зависят от категории товара и суммы. Актуальные условия запрашиваются через API:

$terms = Http::withHeaders([ 'X-Partner-Id' => env('KP_PARTNER_ID'), 'X-Partner-Token' => env('KP_TOKEN'), ])->get(self::BASE_URL . '/terms', [ 'amount' => $order->total, 'category' => $product->kp_category_code, ])->json('available_terms'); 

Если API возвращает пустой массив — товар или сумма не подходят под условия рассрочки. Нужно скрыть опцию оплаты «Картой покупок» для этой позиции.

Сравнение сроков по категориям

Как отладить ошибочную заявку?

Типичные ошибки: неверный amount (отправляем строку вместо числа), неправильный term (значение не из списка) или невалидный phone покупателя. Лучшая практика — логировать полный ответ API и проверять поле errors. Например, 422 Unprocessable Entity с массивом ошибок по каждому полю. Мы включаем в интеграцию endpoint для ручного повторного запроса статуса: GET /api/admin/kp/{id}, который возвращает последние данные из Карты покупок — это помогает поддержке без обращения к разработчикам.

Что входит в работу

Гарантируем качество: исходный код остаётся вашим, мы предоставляем гарантию на 3 месяца бесплатной поддержки после деплоя. Получите консультацию прямо сейчас — оценим сложность и сроки вашего проекта. Закажите оценку — ответим в течение рабочего дня.