Інтеграція розстрочки Карта покупок на сайт

Інтеграція розстрочки Karta Pokupok на веб-сайт

"Karta Pokupok" — білоруська карта розстрочки від Karta Pokupok LLC (раніше пов'язана з Meridian Bank). Працює за тією ж моделлю, що й Halva: власник отримує товар зараз, платить рівними частинами без відсотків, магазин отримує повну суму одразу з урахуванням комісії. Значний охват серед білоруських покупців — карта видається в великих торговельних мережах.

Архітектура інтеграції

Інтеграція будується через 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(),
    ]);
}

Калькулятор розстрочки на веб-сайті

Відображення щомісячного платежу поруч з ціною — стандартна практика. Розрахунок простий: сума ділиться на кількість місяців:

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>{' '}
      розстрочкою через "Karta Pokupok"
    </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 повертає порожній масив — товар або сума не відповідають умовам розстрочки. Варіант оплати "Karta Pokupok" повинен бути приховано для цього предмету.

Статус запиту

Крім webhook, статус запиту можна запросити вручну — корисно для сторінки повернення:

$status = Http::withHeaders([...])
    ->get(self::BASE_URL . '/applications/' . $applicationId)
    ->json('status');

Період підключення до програми складає близько 5 робочих днів. Потрібно буде надати дані про юридичну особу, асортимент і обіг.