Webhook de pago QR de Kaspi: idempotencia, verificación de firma y protección contra doble emisión
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
paiddespués deexpiredo repetirpaidno cambia nada. - El importe se verifica con el importe que tú mismo anotaste al emitir la factura. El campo
amountde 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
===. UtilicetimingSafeEqualy verifique la longitud de los buffers antes de llamar; de lo contrario, se generará una excepción. - Importes en
float. Almacenar en tiyns onumeric. - Idempotencia a nivel de código (
if (order.paid) return) sin transacción. Dos solicitudes simultáneas veránpaid = 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.