Kaspi QR-Zahlungs-Webhook: Idempotenz, Signaturprüfung und Schutz vor Doppelausstellung
Lassen Sie uns zunächst die Begriffe klären
„Doppelabbuchung“ und „Doppelverarbeitung“ sind unterschiedliche Probleme. Wenn für eine Bestellung zwei Zahlungsaufforderungen erstellt werden (der Käufer hat zweimal auf „Bezahlen“ geklickt und Sie haben den QR zweimal ausgestellt), wird der Betrag doppelt abgebucht. Doppelte Bearbeitung – wenn das Zahlungssystem die Benachrichtigung erneut sendet und Sie den Restbetrag zweimal belasten oder die Bestellung zweimal versenden. Sie werden an verschiedenen Stellen gelöst und der Artikel behandelt beide.
Entnehmen Sie das Anforderungsformat, den Signatur-Header-Namen und den Feldsatz der Integrationsdokumentation, die Sie bei der Verbindung mit Kaspi erhalten. Nachfolgende Namen wie X-Signature, paymentId, amount sind Platzhalter: Ersetzen Sie sie durch tatsächliche. Sollte der Anbieter die Benachrichtigungen nicht signieren, wird im Folgenden beschrieben, wie Sie dies kompensieren können.
Tische
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)
);Ein teilweise eindeutiger Index erlaubt keine Erstellung einer zweiten pending-Zahlung für eine Bestellung, selbst wenn zwei Anfragen gleichzeitig eingehen. Der Abrechnungscode gibt im Konfliktfall einfach den bereits vorhandenen QR zurück.
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();
}
}Wichtige Entscheidungen:
- Schreiben Sie in `webhook_events` und ändern Sie den Status in einer Transaktion. Wenn die Verarbeitung fehlschlägt, wird der Ereignisschlüssel zusammen mit ihm zurückgesetzt und die erneute Zustellung wird erneut verarbeitet.
- `FOR UPDATE` sperrt die Zahlungszeile, sodass zwei parallele Benachrichtigungen die
status = 'pending'-Prüfung nicht gleichzeitig bestehen. - Der Zustandsübergang erfolgt nur vorwärts. Die Benachrichtigung von
paidnachexpiredoder die Wiederholung vonpaidändert nichts. - Der Betrag wird mit dem Betrag verifiziert, den Sie selbst bei der Rechnungsstellung notiert haben. Das Feld
amounteines Webhooks wird niemals als Quelle der Wahrheit verwendet. - Versand, Briefe, Rechnungen – nicht im Prozessor. Platzieren Sie die Aufgabe in einer Warteschlange (oder in einer Postausgangstabelle) in derselben Transaktion und führen Sie sie separat aus. Der Abfertiger muss schnell reagieren, andernfalls betrachtet der Anbieter die Zustellung als fehlgeschlagen und wiederholt sie.
Wenn keine Unterschrift vorhanden ist
Einige Integrationen signieren Benachrichtigungen nicht oder anders als Body-HMAC. Behandeln Sie den Webhook dann als „Zahlungsscheck“-Signal: Nachdem Sie ihn erhalten haben, fordern Sie den Status über die API des Anbieters mit Ihrer Kennung an und ändern Sie den Status nur basierend auf der API-Antwort. Begrenzen Sie außerdem eingehende Adressen, wenn der Anbieter eine Liste davon veröffentlicht.
Häufige Fehler
- Die Signatur wird ab
JSON.stringify(await req.json())gezählt. Die Reihenfolge der Schlüssel und Leerzeichen weicht vom Original ab und die Signatur stimmt nicht überein. Wir brauchen Rohtext. - Vergleich der Signaturen über
===. Verwenden SietimingSafeEqualund überprüfen Sie vor dem Aufruf die Länge der Puffer, andernfalls wird eine Ausnahme ausgelöst. - Beträge in
float. In Tiyns odernumericspeichern. - Idempotenz auf Codeebene (
if (order.paid) return) ohne Transaktion. Bei zwei gleichzeitigen Anfragen wird jeweilspaid = falseangezeigt.
Wenn weniger genug ist
Wenn Sie Einzelzahlungen akzeptieren und Bestellungen manuell bearbeiten, ist ein eindeutiger Schlüssel mit external_id und ein manueller Abgleich im persönlichen Konto des Verkäufers ausreichend. Event-Tisch, Warteschlange und Postausgang rechnen sich dort, wo nach der Bezahlung automatisch etwas passiert.