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

Kaspi QR ödeme web kancası: geçicilik, imza doğrulama ve çifte düzenlemeye karşı koruma

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

Öncelikle terimleri açıklığa kavuşturalım

“Çifte borçlandırma” ve “çifte işlem” farklı sorunlardır. Bir sipariş için iki ödeme talebi oluşturulduğunda para iki kez borçlandırılır (alıcı iki kez "Öde"ye tıkladı ve siz QR'yi iki kez verdiniz). Çift işleme - ödeme sistemi bildirimi tekrar gönderdiğinde ve bakiyeyi iki kez tahsil ettiğinizde veya siparişi iki kez gönderdiğinizde. Bunlar farklı yerlerde çözülüyor ve makale her ikisini de kapsıyor.

Kaspi'ye bağlanırken aldığınız entegrasyon belgelerinden istek biçimini, imza başlığı adını ve alan kümesini alın. Aşağıdaki X-Signature, paymentId, amount gibi adlar yer tutuculardır: bunları gerçek olanlarla değiştirin. Sağlayıcının bildirimleri imzalamaması durumunda bunun nasıl telafi edileceği aşağıda açıklanmıştır.

Tablolar

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

Kısmi benzersiz bir dizin, iki istek aynı anda gelse bile bir sipariş için ikinci bir pending ödemesi oluşturulmasına izin vermez. Anlaşmazlık durumunda faturalama kodu yalnızca mevcut QR'yi döndürür.

Next.js'deki işleyici

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

Temel kararlar:

  • `webhook_events`'a yazın ve durumu tek bir işlemde değiştirin. İşleme başarısız olursa, olay anahtarı da onunla birlikte geri alınacak ve yeniden dağıtım yeniden işlenecektir.
  • `FOR UPDATE` ödeme hattını kilitler, böylece iki paralel bildirim aynı anda status = 'pending' kontrolünden geçemez.
  • Durum geçişi yalnızca ileri yöndedir. expired'dan sonra paid'a bildirimde bulunmak veya paid'yi tekrarlamak hiçbir şeyi değiştirmez.
  • Tutar, faturayı düzenlerken sizin yazdığınız tutarla doğrulanır. Bir webhook'un amount alanı hiçbir zaman doğruluk kaynağı olarak kullanılmaz.
  • Sevkiyat, mektuplar, tahakkuklar - işlemcinin içinde değil. Görevi aynı işlemde bir kuyruğa (veya bir giden kutusu tablosuna) yerleştirin ve ayrı olarak yürütün. İşleyici hızlı bir şekilde yanıt vermelidir, aksi takdirde sağlayıcı teslimatın başarısız olduğunu düşünecek ve bunu tekrarlayacaktır.

İmza yoksa

Bazı entegrasyonlar bildirimleri imzalamaz veya bunları gövde HMAC'inden farklı şekilde imzalamaz. Ardından web kancasını bir "ödemeyi kontrol et" sinyali olarak değerlendirin: bunu aldıktan sonra, tanımlayıcınızı kullanarak sağlayıcının API'si aracılığıyla durumu isteyin ve durumu yalnızca API yanıtına göre değiştirin. Ayrıca, sağlayıcının bir liste yayınlaması durumunda gelen adresleri sınırlayın.

Yaygın hatalar

  • İmza JSON.stringify(await req.json())'dan sayılır. Tuşların ve boşlukların sırası orijinalinden farklı ve imza eşleşmiyor. Ham gövde metnine ihtiyacımız var.
  • === aracılığıyla imzaların karşılaştırılması. timingSafeEqual kullanın ve çağırmadan önce arabelleklerin uzunluğunu kontrol edin, aksi takdirde bir istisna oluşturacaktır.
  • float cinsinden tutarlar. Tiyns veya numeric içinde saklayın.
  • İşlem olmadan kod düzeyinde (if (order.paid) return) önemsizlik. Eş zamanlı iki isteğin her ikisi de paid = false görecektir.

Daha azı yeterli olduğunda

Tekli ödemeleri kabul ediyorsanız ve siparişleri manuel olarak işliyorsanız, external_id kullanan benzersiz bir anahtar ve satıcının kişisel hesabındaki manuel mutabakat yeterlidir. Etkinlik tablosu, kuyruk ve giden kutusu, ödeme yapıldıktan sonra otomatik olarak bir şeyler gerçekleştiğinde karşılığını verir.

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

Ещё на vbcd4u.com