Вебхук оплати 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 окупаються там, де після оплати щось відбувається автоматично.