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