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

Webhook de pago QR de Kaspi: idempotencia, verificación de firma y protección contra doble emisión

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

Primero, aclaremos los términos.

El “doble débito” y el “doble procesamiento” son problemas diferentes. El dinero se debita dos veces cuando se crean dos solicitudes de pago para un pedido (el comprador hizo clic en "Pagar" dos veces y usted emitió el QR dos veces). Procesamiento doble: cuando el sistema de pago envía la notificación nuevamente y usted carga el saldo dos veces o envía el pedido dos veces. Se resuelven en diferentes lugares y el artículo cubre ambos.

Tome el formato de solicitud, el nombre del encabezado de la firma y el conjunto de campos de la documentación de integración que recibe al conectarse a Kaspi. Los siguientes nombres como X-Signature, paymentId, amount son ​​marcadores de posición: reemplácelos con los reales. Si el proveedor no firma las notificaciones, a continuación se describe cómo compensarlo.

Tablas

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)
);

Un índice único parcial no permitirá crear un segundo pago pending para un pedido, incluso si llegan dos solicitudes al mismo tiempo. El código de facturación en caso de conflicto simplemente devuelve el QR ya existente.

Controlador en 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();
  }
}

Decisiones clave:

  • Escribe en `webhook_events` y cambia el estado en una transacción. Si el procesamiento falla, la clave del evento se revertirá junto con ella y la reenvío se procesará nuevamente.
  • `FOR UPDATE` bloquea la línea de pago para que dos notificaciones paralelas no pasen la verificación status = 'pending' al mismo tiempo.
  • La transición de estado es solo hacia adelante. Notificar a paid después de expired o repetir paid no cambia nada.
  • El importe se verifica con el importe que tú mismo anotaste al emitir la factura. El campo amount de un webhook nunca se utiliza como fuente de verdad.
  • Envíos, cartas, acumulaciones - no dentro del procesador. Coloque la tarea en una cola (o en una tabla de bandeja de salida) en la misma transacción y ejecútela por separado. El transportista debe responder rápidamente, de lo contrario el proveedor considerará la entrega fallida y la repetirá.

Si no hay firma

Algunas integraciones no firman notificaciones o las firman de manera diferente al cuerpo HMAC. Luego, trate el webhook como una señal de “pago con cheque”: una vez recibido, solicite el estado a través de la API del proveedor utilizando su identificador y cambie el estado solo según la respuesta de la API. Además, limite las direcciones entrantes si el proveedor publica una lista de ellas.

Errores comunes

  • La firma se cuenta desde JSON.stringify(await req.json()). El orden de las claves y los espacios es diferente al original y la firma no coincide. Necesitamos texto del cuerpo sin formato.
  • Comparación de firmas vía ===. Utilice timingSafeEqual y verifique la longitud de los buffers antes de llamar; de lo contrario, se generará una excepción.
  • Importes en float. Almacenar en tiyns o numeric.
  • Idempotencia a nivel de código (if (order.paid) return) sin transacción. Dos solicitudes simultáneas verán paid = false.

Cuando menos es suficiente

Si acepta pagos únicos y procesa pedidos manualmente, una clave única usando external_id y una conciliación manual en la cuenta personal del vendedor es suficiente. La tabla de eventos, la cola y la bandeja de salida dan resultados donde algo sucede automáticamente después del pago.

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

Ещё на vbcd4u.com