Інтеграція сервісу «Карта покупок»: 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 місяці безкоштовної підтримки після деплою. Отримайте консультацію прямо зараз — оцінимо складність та терміни вашого проєкту. Замовте оцінку — відповімо протягом робочого дня.