Вебхук оплаты Kaspi QR: идемпотентность, проверка подписи и защита от двойной выдачи
Сначала уточним термины
«Двойное списание» и «двойная обработка» — разные проблемы. Деньги дважды списываются, когда для одного заказа создаются два платёжных запроса (покупатель дважды нажал «Оплатить», и вы дважды выставили 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 окупаются там, где после оплаты что-то происходит автоматически.