Webhook de paiement Kaspi QR : idempotence, vérification de signature et protection contre la double émission
Tout d'abord, clarifions les termes
Le « double débit » et le « double traitement » sont des problèmes différents. L'argent est débité deux fois lorsque deux demandes de paiement sont créées pour une commande (l'acheteur a cliqué deux fois sur « Payer » et vous avez émis le QR deux fois). Double traitement : lorsque le système de paiement envoie à nouveau la notification et que vous facturez le solde deux fois ou expédiez la commande deux fois. Ils sont résolus à différents endroits et l’article couvre les deux.
Prenez le format de demande, le nom de l'en-tête de signature et l'ensemble des champs de la documentation d'intégration que vous recevez lors de la connexion à Kaspi. Les noms ci-dessous comme X-Signature, paymentId, amount sont des espaces réservés : remplacez-les par les noms réels. Si le fournisseur ne signe pas les notifications, vous trouverez ci-dessous comment compenser cela.
Tableaux
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 index unique partiel ne permettra pas de créer un deuxième pending-paiement pour une commande, même si deux demandes arrivent en même temps. Le code de facturation en cas de conflit renvoie simplement le QR déjà existant.
Gestionnaire dans 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();
}
}Décisions clés :
- Écrivez dans `webhook_events` et modifiez le statut en une seule transaction. Si le traitement échoue, la clé d'événement sera annulée avec elle et la relivraison sera à nouveau traitée.
- `FOR UPDATE` verrouille la ligne de paiement afin que deux notifications parallèles ne réussissent pas le contrôle
status = 'pending'en même temps. - La transition d'état s'effectue uniquement vers l'avant. Notifier
paidaprèsexpiredou répéterpaidne change rien. - Le montant est vérifié avec le montant que vous avez vous-même noté lors de l'émission de la facture. Le champ
amountd'un webhook n'est jamais utilisé comme source de vérité. - Envoi, lettres, régularisations - pas à l'intérieur du processeur. Placez la tâche dans une file d'attente (ou dans une table de boîte d'envoi) dans la même transaction et exécutez-la séparément. Le manutentionnaire doit réagir rapidement, sinon le prestataire considérera la livraison comme un échec et la répétera.
S'il n'y a pas de signature
Certaines intégrations ne signent pas les notifications ou les signent différemment du corps HMAC. Traitez ensuite le webhook comme un signal « paiement par chèque » : après l'avoir reçu, demandez le statut via l'API du fournisseur à l'aide de votre identifiant et modifiez le statut uniquement en fonction de la réponse de l'API. De plus, limitez les adresses entrantes si le fournisseur en publie une liste.
Erreurs courantes
- La signature est décomptée à partir de
JSON.stringify(await req.json()). L'ordre des touches et des espaces est différent de l'original et la signature ne correspond pas. Nous avons besoin d’un corps de texte brut. - Comparaison des signatures via
===. UtiliseztimingSafeEqualet vérifiez la longueur des tampons avant d'appeler, sinon une exception sera levée. - Montants en
float. Stocker dans tiyns ounumeric. - Idempotence au niveau du code (
if (order.paid) return) sans transaction. Deux requêtes simultanées verront toutes deuxpaid = false.
Quand moins suffit
Si vous acceptez les paiements uniques et traitez les commandes manuellement, une clé unique utilisant external_id et un rapprochement manuel dans le compte personnel du vendeur suffisent. La table des événements, la file d'attente et la boîte d'envoi sont payantes, car quelque chose se produit automatiquement après le paiement.