Kaspi QR to'lov veb-huk: identifikatorlik, imzoni tekshirish va ikki marta chiqarishdan himoya
Birinchidan, shartlarga aniqlik kiritamiz
"Ikki marta debet" va "ikki marta ishlov berish" turli xil muammolardir. Bitta buyurtma uchun ikkita to'lov so'rovi yaratilganda pul ikki marta debetlanadi (xaridor "To'lash" tugmasini ikki marta bosgan va siz ikki marta QR chiqargansiz). Ikki marta ishlov berish - to'lov tizimi bildirishnomani yana yuborganda va siz balansni ikki marta to'laysiz yoki buyurtmani ikki marta jo'natasiz. Ular turli joylarda hal qilinadi va maqola ikkalasini ham qamrab oladi.
Kaspi-ga ulanishda olingan integratsiya hujjatlaridan so'rov formatini, imzo sarlavhasi nomini va maydonlar to'plamini oling. Quyida X-Signature, paymentId, amount kabi nomlar joy egallaydi: ularni haqiqiylari bilan almashtiring. Agar provayder bildirishnomalarni imzolamasa, buni qanday qoplash kerakligi quyida tasvirlangan.
Jadvallar
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)
);Qisman noyob indeks buyurtma uchun ikkinchi pending to'lovini yaratishga imkon bermaydi, hatto bir vaqtning o'zida ikkita so'rov kelib tushsa ham. Qarama-qarshilik bo'lsa, hisob-kitob kodi mavjud QR-ni qaytaradi.
Next.js da ishlov beruvchi
// 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();
}
}Asosiy qarorlar:
- `webhook_events` ga yozing va bitta tranzaksiyada holatni o'zgartiring. Agar ishlov berish muvaffaqiyatsiz tugasa, voqea kaliti u bilan birga orqaga qaytariladi va qayta yetkazib berish qayta ishlanadi.
- `FOR UPDATE` to‘lov liniyasini bloklaydi, shuning uchun ikkita parallel bildirishnoma bir vaqtning o‘zida
status = 'pending'tekshiruvidan o‘tmaydi. - Holatga oʻtish faqat oldinga.
expireddan keyinpaidga xabar berish yokipaidni takrorlash hech narsani oʻzgartirmaydi. - Miqdor hisob-fakturani rasmiylashtirishda siz yozgan summa bilan tasdiqlanadi. Webhukdagi
amountmaydoni hech qachon haqiqat manbai sifatida ishlatilmaydi. - Yuk tashish, xatlar, hisob-kitoblar - protsessor ichida emas. Vazifani bir xil tranzaksiyada navbatga (yoki chiqish qutisi jadvaliga) qo'ying va uni alohida bajaring. Ishlovchi tezda javob berishi kerak, aks holda provayder etkazib berishni muvaffaqiyatsiz deb hisoblaydi va uni takrorlaydi.
Agar imzo bo'lmasa
Ba'zi integratsiyalar bildirishnomalarni imzolamaydi yoki ularni HMAC tanasidan farqli ravishda imzolamaydi. Keyin veb-hukni "to'lovni tekshirish" signali sifatida ko'rib chiqing: uni qabul qilib, identifikatoringiz yordamida provayderning API orqali statusni so'rang va faqat API javobi asosida holatni o'zgartiring. Bundan tashqari, agar provayder ularning ro'yxatini e'lon qilsa, kiruvchi manzillarni cheklang.
Umumiy xatolar
- Imzo
JSON.stringify(await req.json())dan boshlab hisoblanadi. Tugmalar va bo'shliqlar tartibi asl nusxadan farq qiladi va imzo mos kelmaydi. Bizga asosiy matn kerak. ===orqali imzolarni solishtirish. Qo'ng'iroq qilishdan oldintimingSafeEqualdan foydalaning va buferlar uzunligini tekshiring, aks holda u istisno qiladi.floatdagi summalar. Tiyin yokinumericda saqlang.- Tranzaksiyasiz kod darajasida identifikatorlik (
if (order.paid) return). Bir vaqtning o'zida ikkita so'rovpaid = falseni ko'radi.
Qachon kamroq bo'lsa
Agar siz bitta toʻlovni qabul qilsangiz va buyurtmalarni qoʻlda qayta ishlasangiz, sotuvchining shaxsiy hisobidagi external_id va qoʻlda solishtiruvdan foydalangan holda noyob kalit yetarli boʻladi. Voqealar jadvali, navbat va chiqish qutisi to'lovdan so'ng avtomatik ravishda biror narsa sodir bo'lganda to'lanadi.