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

Kaspi QR-betalingswebhook: idempotentie, handtekeningverificatie en bescherming tegen dubbele uitgifte

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

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 paid na expired of het herhalen van paid verandert niets.
  • Het bedrag wordt geverifieerd met het bedrag dat u zelf heeft opgeschreven bij het uitreiken van de factuur. Het veld amount van 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 ===. Gebruik timingSafeEqual en controleer de lengte van de buffers voordat u aanroept, anders genereert het een uitzondering.
  • Bedragen in float. Opslaan in tiyns of numeric.
  • Idempotentie op codeniveau (if (order.paid) return) zonder transactie. Bij twee gelijktijdige verzoeken wordt paid = false weergegeven.

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.

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

Ещё на vbcd4u.com