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

Webhook de paiement Kaspi QR : idempotence, vérification de signature et protection contre la double émission

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

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 paid après expired ou répéter paid ne 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 amount d'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 ===. Utilisez timingSafeEqual et vérifiez la longueur des tampons avant d'appeler, sinon une exception sera levée.
  • Montants en float. Stocker dans tiyns ou numeric.
  • Idempotence au niveau du code (if (order.paid) return) sans transaction. Deux requêtes simultanées verront toutes deux paid = 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.

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

Ещё на vbcd4u.com