Kaspi QR-betalingswebhook: idempotentie, handtekeningverificatie en bescherming tegen dubbele uitgifte
Laten we eerst de voorwaarden verduidelijken
“Dubbele afschrijving” en “dubbele verwerking” zijn verschillende problemen. Er wordt twee keer geld afgeschreven als er voor één bestelling twee betaalverzoeken worden aangemaakt (de koper heeft twee keer op “Betalen” geklikt en jij hebt twee keer de QR uitgegeven). Dubbele verwerking - wanneer het betalingssysteem de melding opnieuw verzendt en u het saldo tweemaal in rekening brengt of de bestelling tweemaal verzendt. Ze worden op verschillende plaatsen opgelost en het artikel behandelt beide.
Neem het verzoekformaat, de naam van de handtekeningkop en de set velden over uit de integratiedocumentatie die u ontvangt wanneer u verbinding maakt met Kaspi. Onderstaande namen als X-Signature, paymentId, amount zijn tijdelijke aanduidingen: vervang ze door daadwerkelijke namen. Indien de aanbieder de meldingen niet ondertekent, staat hieronder beschreven hoe u dit kunt compenseren.
Tafels
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)
);Een gedeeltelijke unieke index maakt het niet mogelijk om een tweede pending-betaling voor een bestelling te maken, zelfs als er twee aanvragen tegelijkertijd binnenkomen. De factuurcode retourneert in geval van conflict eenvoudigweg de reeds bestaande QR.
Handler in 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();
}
}Belangrijkste beslissingen:
- Schrijf naar `webhook_events` en wijzig de status in één transactie. Als de verwerking mislukt, wordt de gebeurtenissleutel mee teruggedraaid en wordt de herlevering opnieuw verwerkt.
- `FOR UPDATE` vergrendelt de betalingsregel, zodat twee parallelle meldingen niet tegelijkertijd door de
status = 'pending'-controle komen. - Statusovergang is alleen voorwaarts. Het melden van
paidnaexpiredof het herhalen vanpaidverandert niets. - Het bedrag wordt geverifieerd met het bedrag dat u zelf heeft opgeschreven bij het uitreiken van de factuur. Het veld
amountvan een webhook wordt nooit gebruikt als bron van waarheid. - Verzending, brieven, overlopende posten - niet in de processor. Plaats de taak in een wachtrij (of in een outbox-tabel) in dezelfde transactie en voer deze afzonderlijk uit. De behandelaar moet snel reageren, anders beschouwt de aanbieder de bezorging als mislukt en herhaalt deze.
Als er geen handtekening is
Sommige integraties ondertekenen geen meldingen of ondertekenen deze anders dan hoofd-HMAC. Beschouw de webhook vervolgens als een signaal van “chequebetaling”: nadat u deze heeft ontvangen, vraagt u de status op via de API van de provider met behulp van uw ID en wijzigt u de status alleen op basis van het API-antwoord. Beperk bovendien de inkomende adressen als de provider er een lijst van publiceert.
Veelvoorkomende fouten
- De handtekening wordt geteld vanaf
JSON.stringify(await req.json()). De volgorde van de toetsen en spaties wijkt af van het origineel en de handtekening komt niet overeen. We hebben onbewerkte hoofdtekst nodig. - Vergelijking van handtekeningen via
===. GebruiktimingSafeEqualen controleer de lengte van de buffers voordat u aanroept, anders genereert het een uitzondering. - Bedragen in
float. Opslaan in tiyns ofnumeric. - Idempotentie op codeniveau (
if (order.paid) return) zonder transactie. Bij twee gelijktijdige verzoeken wordtpaid = falseweergegeven.
Als minder genoeg is
Als u afzonderlijke betalingen accepteert en bestellingen handmatig verwerkt, is een unieke sleutel met behulp van external_id en handmatige afstemming in het persoonlijke account van de verkoper voldoende. De evenemententafel, wachtrij en outbox lonen waar er na betaling automatisch iets gebeurt.