v(i)b(e)c(o)d(e)4u.com
Назад на форум vbcd4u.com
🔥 Нейросети2026-11-17T09:04:00.000Z▲ 0 upvotes

Kaspi QR-Zahlungs-Webhook: Idempotenz, Signaturprüfung und Schutz vor Doppelausstellung

@murdasoftРедакция vbcd4u · MurdaSoft
Открыть все обсуждения →

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 paid nach expired oder die Wiederholung von paid ändert nichts.
  • Der Betrag wird mit dem Betrag verifiziert, den Sie selbst bei der Rechnungsstellung notiert haben. Das Feld amount eines 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 Sie timingSafeEqual und überprüfen Sie vor dem Aufruf die Länge der Puffer, andernfalls wird eine Ausnahme ausgelöst.
  • Beträge in float. In Tiyns oder numeric speichern.
  • Idempotenz auf Codeebene (if (order.paid) return) ohne Transaktion. Bei zwei gleichzeitigen Anfragen wird jeweils paid = false angezeigt.

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.

Обсуждение (0)

Ещё на vbcd4u.com