Kaspi QR ödeme web kancası: geçicilik, imza doğrulama ve çifte düzenlemeye karşı koruma
Öncelikle terimleri açıklığa kavuşturalım
“Çifte borçlandırma” ve “çifte işlem” farklı sorunlardır. Bir sipariş için iki ödeme talebi oluşturulduğunda para iki kez borçlandırılır (alıcı iki kez "Öde"ye tıkladı ve siz QR'yi iki kez verdiniz). Çift işleme - ödeme sistemi bildirimi tekrar gönderdiğinde ve bakiyeyi iki kez tahsil ettiğinizde veya siparişi iki kez gönderdiğinizde. Bunlar farklı yerlerde çözülüyor ve makale her ikisini de kapsıyor.
Kaspi'ye bağlanırken aldığınız entegrasyon belgelerinden istek biçimini, imza başlığı adını ve alan kümesini alın. Aşağıdaki X-Signature, paymentId, amount gibi adlar yer tutuculardır: bunları gerçek olanlarla değiştirin. Sağlayıcının bildirimleri imzalamaması durumunda bunun nasıl telafi edileceği aşağıda açıklanmıştır.
Tablolar
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)
);Kısmi benzersiz bir dizin, iki istek aynı anda gelse bile bir sipariş için ikinci bir pending ödemesi oluşturulmasına izin vermez. Anlaşmazlık durumunda faturalama kodu yalnızca mevcut QR'yi döndürür.
Next.js'deki işleyici
// 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();
}
}Temel kararlar:
- `webhook_events`'a yazın ve durumu tek bir işlemde değiştirin. İşleme başarısız olursa, olay anahtarı da onunla birlikte geri alınacak ve yeniden dağıtım yeniden işlenecektir.
- `FOR UPDATE` ödeme hattını kilitler, böylece iki paralel bildirim aynı anda
status = 'pending'kontrolünden geçemez. - Durum geçişi yalnızca ileri yöndedir.
expired'dan sonrapaid'a bildirimde bulunmak veyapaid'yi tekrarlamak hiçbir şeyi değiştirmez. - Tutar, faturayı düzenlerken sizin yazdığınız tutarla doğrulanır. Bir webhook'un
amountalanı hiçbir zaman doğruluk kaynağı olarak kullanılmaz. - Sevkiyat, mektuplar, tahakkuklar - işlemcinin içinde değil. Görevi aynı işlemde bir kuyruğa (veya bir giden kutusu tablosuna) yerleştirin ve ayrı olarak yürütün. İşleyici hızlı bir şekilde yanıt vermelidir, aksi takdirde sağlayıcı teslimatın başarısız olduğunu düşünecek ve bunu tekrarlayacaktır.
İmza yoksa
Bazı entegrasyonlar bildirimleri imzalamaz veya bunları gövde HMAC'inden farklı şekilde imzalamaz. Ardından web kancasını bir "ödemeyi kontrol et" sinyali olarak değerlendirin: bunu aldıktan sonra, tanımlayıcınızı kullanarak sağlayıcının API'si aracılığıyla durumu isteyin ve durumu yalnızca API yanıtına göre değiştirin. Ayrıca, sağlayıcının bir liste yayınlaması durumunda gelen adresleri sınırlayın.
Yaygın hatalar
- İmza
JSON.stringify(await req.json())'dan sayılır. Tuşların ve boşlukların sırası orijinalinden farklı ve imza eşleşmiyor. Ham gövde metnine ihtiyacımız var. ===aracılığıyla imzaların karşılaştırılması.timingSafeEqualkullanın ve çağırmadan önce arabelleklerin uzunluğunu kontrol edin, aksi takdirde bir istisna oluşturacaktır.floatcinsinden tutarlar. Tiyns veyanumericiçinde saklayın.- İşlem olmadan kod düzeyinde (
if (order.paid) return) önemsizlik. Eş zamanlı iki isteğin her ikisi depaid = falsegörecektir.
Daha azı yeterli olduğunda
Tekli ödemeleri kabul ediyorsanız ve siparişleri manuel olarak işliyorsanız, external_id kullanan benzersiz bir anahtar ve satıcının kişisel hesabındaki manuel mutabakat yeterlidir. Etkinlik tablosu, kuyruk ve giden kutusu, ödeme yapıldıktan sonra otomatik olarak bir şeyler gerçekleştiğinde karşılığını verir.