v(i)b(e)c(o)d(e)4u.com
Назад на форум vbcd4u.com
🔥 Нейросети2026-11-17T09:04:00.000Z▲ 0 upvotes

Вебхук оплати Kaspi QR: ідемпотентність, перевірка підпису та захист від подвійної видачі

@murdasoftРедакция vbcd4u · MurdaSoft
Открыть все обсуждения →

Спочатку уточнимо терміни

«Подвійне списання» та «подвійне оброблення» — різні проблеми. Гроші двічі списуються, коли для одного замовлення створюються два платіжні запити (покупець двічі натиснув «Оплатити», і ви двічі виставили QR). Подвійна обробка — коли платіжна система надсилає повідомлення повторно, а двічі нараховуєте баланс або двічі відвантажуєте замовлення. Вирішуються вони у різних місцях, і стаття закриває обидві.

Формат запитів, ім'я заголовка підпису та набір полів беріть із документації інтеграції, яку ви отримуєте при підключенні до Kaspi. Нижче назви на кшталт X-Signature, paymentId, amount — плейсхолдери: замініть їх фактичними. Якщо провайдер не підписує повідомлення, то нижче описано, чим це компенсувати.

Таблиці

CREATE TABLE payments (
  id            bigserial PRIMARY KEY,
  order_id      bigint NOT NULL REFERENCES orders(id),
  provider      text   NOT NULL DEFAULT 'kaspi',
  external_id   text,                         -- идентификатор платежа у провайдера
  amount_tiyn   bigint NOT NULL,              -- сумма в минимальных единицах, без float
  status        text   NOT NULL CHECK (status IN ('pending','paid','failed','expired')),
  created_at    timestamptz NOT NULL DEFAULT now(),
  paid_at       timestamptz
);

-- один активный платёж на заказ: защита от двойного выставления
CREATE UNIQUE INDEX payments_one_pending_per_order
  ON payments (order_id) WHERE status = 'pending';

-- одно уведомление обрабатывается один раз
CREATE TABLE webhook_events (
  provider     text NOT NULL,
  event_key    text NOT NULL,
  received_at  timestamptz NOT NULL DEFAULT now(),
  PRIMARY KEY (provider, event_key)
);

Частковий унікальний індекс не дасть створити другий pending-платіж для замовлення, навіть якщо два запити надійдуть одночасно. Код виставлення рахунку при конфлікті просто повертає QR, що вже існує.

Обробник у Next.js

// app/api/webhooks/kaspi/route.ts
import { createHmac, timingSafeEqual } from "node:crypto";
import { pool } from "@/lib/db";

export const runtime = "nodejs";

function verify(rawBody: string, signature: string | null): boolean {
  if (!signature) return false;
  const expected = createHmac("sha256", process.env.KASPI_WEBHOOK_SECRET!)
    .update(rawBody, "utf8")
    .digest("hex");
  const a = Buffer.from(expected, "hex");
  const b = Buffer.from(signature, "hex");
  return a.length === b.length && timingSafeEqual(a, b);
}

export async function POST(req: Request) {
  const raw = await req.text();                    // подпись считается по сырому телу
  if (!verify(raw, req.headers.get("x-signature"))) {
    return new Response("bad signature", { status: 401 });
  }

  const evt = JSON.parse(raw) as { paymentId: string; orderId: string; amount: number; status: string };
  const client = await pool.connect();
  try {
    await client.query("BEGIN");

    const inserted = await client.query(
      `INSERT INTO webhook_events (provider, event_key) VALUES ('kaspi', $1)
       ON CONFLICT DO NOTHING RETURNING event_key`,
      [`${evt.paymentId}:${evt.status}`]
    );
    if (inserted.rowCount === 0) {            // уже обработано
      await client.query("ROLLBACK");
      return Response.json({ ok: true, duplicate: true });
    }

    const { rows } = await client.query(
      `SELECT id, amount_tiyn, status FROM payments
       WHERE order_id = $1 AND provider = 'kaspi' FOR UPDATE`,
      [evt.orderId]
    );
    const payment = rows[0];
    if (!payment) throw new Error("unknown order");

    if (evt.status === "paid" && payment.status === "pending") {
      if (BigInt(payment.amount_tiyn) !== BigInt(Math.round(evt.amount * 100))) {
        throw new Error("amount mismatch");
      }
      await client.query(
        `UPDATE payments SET status = 'paid', external_id = $2, paid_at = now() WHERE id = $1`,
        [payment.id, evt.paymentId]
      );
      await client.query(`UPDATE orders SET state = 'paid' WHERE id = $1`, [evt.orderId]);
    }

    await client.query("COMMIT");
    return Response.json({ ok: true });
  } catch (e) {
    await client.query("ROLLBACK");
    console.error("kaspi webhook", e);
    return new Response("error", { status: 500 });  // провайдер повторит доставку
  } finally {
    client.release();
  }
}

Ключові рішення:

  • Запис у `webhook_events` та зміна статусу в одній транзакції. Якщо обробка впаде, ключ події відкотиться разом з нею, і повторна доставка обробиться заново.
  • `FOR UPDATE` блокує рядок платежу, тому два паралельні повідомлення не пройдуть перевірку status = 'pending' одночасно.
  • Перехід станів тільки вперед. Повідомлення paid після expired або повторний paid нічого не змінюють.
  • Сума звіряється із сумою, яку ви самі записали при виставленні рахунку. Поле amount з вебхука ніколи не використовується як джерело істини.
  • Відвантаження, листи, нарахування - не всередині оброблювача. Ставте завдання у чергу (чи таблицю outbox) у тому транзакції, а виконуйте окремо. Обробник повинен відповідати швидко, інакше провайдер визнає доставку неуспішною і повторить її.

Якщо підпису немає

Деякі інтеграції не підписують повідомлення або підписують їх інакше, ніж HMAC по тілу. Тоді ставтеся до вебхуку як до сигналу «перевір платеж»: отримавши його, запитайте статус через провайдера API за своїм ідентифікатором і змінюйте стан тільки за відповіддю API. Додатково обмежте вхідні адреси, якщо провайдер публікує їхній список.

Типові помилки

  • Підпис вважається від JSON.stringify(await req.json()). Порядок ключів та пробіли відрізняються від оригіналу, і підпис не співпадає. Потрібен сирого тексту тіла.
  • Порівняння підписів через ===. Використовуйте timingSafeEqual та перевіряйте довжину буферів до виклику, інакше він залишить виняток.
  • Суми в float. Зберігайте в тінах або в numeric.
  • Ідемопотентність на рівні коду (if (order.paid) return) без транзакції. Два одночасні запити обидва побачать paid = false.

Коли вистачить меншого

Якщо ви приймаєте одиничні оплати та обробляєте замовлення вручну, унікального ключа за external_id та ручної звірки в особистому кабінеті продавця достатньо. Таблиця подій, черга та outbox окупаються там, де після оплати щось відбувається автоматично.

Обсуждение (0)

Ещё на vbcd4u.com