Уявіть: покупець уже вибрав товар, додав у кошик, але на етапі оплати бачить лише повну вартість. Якщо немає розстрочки, він може піти. Ми вирішуємо це інтеграцією «Карти покупок» — білоруського сервісу розстрочки, яким користуються понад 500 000 держателів. Середній чек після підключення зростає на 20–30%, конверсія — на 15–20%. За 5 років роботи ми інтегрували 30+ платіжних рішень, тому беремося навіть за нестандартні сценарії.
«Карта покупок» працює за моделлю: покупець платить рівними частками без відсотків, магазин отримує повну суму одразу. Інтеграція через REST API та webhook автоматизує обробку заявок: 99% рішень приходять за 2 хвилини. Комісія сервісу становить 2–4% від суми замовлення, що окупається зростанням продажів.
Чому інтеграція з Картою покупок вигідна?
Порівняно з кредитними картками, розстрочка приваблює більше покупців: не потрібно переплачувати відсотки, а схвалення займає хвилини. Для магазину це зростання середнього чека на 20–30% та зниження відмов на етапі оплати. Інтеграція через REST API швидша та надійніша за ручну обробку — заявки підтверджуються автоматично. Згідно зі звітами наших клієнтів, конверсія зростає на 18–25% вже в перший місяць після підключення.
Як ми налаштовуємо інтеграцію?
Архітектура будується через REST API партнерського кабінету. Послідовність:
- Магазин формує заявку через API → отримує посилання на анкету
- Покупець заповнює анкету та підтверджує розстрочку (SMS-код)
- Webhook повідомляє магазин про статус заявки
- При статусі
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 повертає порожній масив — товар або сума не підходять під умови розстрочки. Потрібно приховати опцію оплати «Картою покупок» для цієї позиції.
Порівняння термінів за категоріями
| Категорія товарів | Доступні терміни (міс.) | Мінімальна сума (BYN) |
|---|---|---|
| Електроніка | 3, 6, 12, 18, 24 | 100 |
| Одяг та взуття | 3, 6, 12 | 50 |
| Побутова техніка | 3, 6, 12, 18, 24 | 150 |
| Спорттовари | 3, 6, 12 | 80 |
Детальніше про безпеку Webhook
Для перевірки справжності запитів використовується HMAC-підпис на основі секретного ключа. Усі вхідні webhook-запити повинні містити заголовок X-Signature. Ми обов'язково валідуємо підпис перед обробкою, щоб запобігти підробці запитів. Також налаштовуємо моніторинг повторних спроб: сервіс Карти покупок перевідправляє webhook до 3 разів з інтервалом 5 хвилин.Як налагодити помилкову заявку?
Типові помилки: невірний amount (відправляємо рядок замість числа), неправильний term (значення не зі списку) або невалідний phone покупця. Найкраща практика — логувати повну відповідь API та перевіряти поле errors. Наприклад, 422 Unprocessable Entity з масивом помилок по кожному полю. Ми включаємо в інтеграцію endpoint для ручного повторного запиту статусу: GET /api/admin/kp/{id}, який повертає останні дані з Карти покупок — це допомагає підтримці без звернення до розробників.
Що входить в роботу
| Етап | Що робимо | Результат |
|---|---|---|
| Аналітика | Вивчаємо поточну платіжну архітектуру, узгоджуємо схему | Технічне завдання |
| Проектування | Проектуємо інтеграцію: API-запити, webhook, сценарії помилок | Документація схеми |
| Реалізація | Пишемо код інтеграції на вашому стеку (Laravel, Symfony, WordPress та ін.) | Робочий код в репозиторії |
| Тестування | Проходимо тестові сценарії: створення, скасування, помилки | Звіт про тестування |
| Деплой | Викочуємо на бойовий сервер, налаштовуємо моніторинг | Доступ до системи моніторингу |
| Навчання | Проводимо демо-сесію для команди підтримки | Інструкція та відеозапис |
Гарантуємо якість: вихідний код залишається вашим, ми надаємо гарантію на 3 місяці безкоштовної підтримки після деплою. Отримайте консультацію прямо зараз — оцінимо складність та терміни вашого проєкту. Замовте оцінку — відповімо протягом робочого дня.