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

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

«Карта покупок» — белорусская карта рассрочки от ООО «Карта покупок» (ранее аффилированная с ЗАО «МТБанк»). Работает по той же модели, что и Халва: держатель получает товар сейчас, платит равными долями без процентов, магазин получает полную сумму сразу за вычетом комиссии. Охват среди белорусских покупателей значительный — карта выдаётся в крупных торговых сетях.

Архитектура интеграции

Интеграция строится через 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>{' '}
      в рассрочку «Карта покупок»
    </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 возвращает пустой массив — товар или сумма не подходят под условия рассрочки. Нужно скрыть опцию оплаты «Картой покупок» для этой позиции.

Статус заявки

Помимо webhook, статус заявки можно запросить вручную — актуально для страницы возврата:

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

Срок подключения к программе — около 5 рабочих дней. Потребуется предоставить данные о юрлице, ассортименте и обороте.