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

Kaspi QR to'lov veb-huk: identifikatorlik, imzoni tekshirish va ikki marta chiqarishdan himoya

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

Birinchidan, shartlarga aniqlik kiritamiz

"Ikki marta debet" va "ikki marta ishlov berish" turli xil muammolardir. Bitta buyurtma uchun ikkita to'lov so'rovi yaratilganda pul ikki marta debetlanadi (xaridor "To'lash" tugmasini ikki marta bosgan va siz ikki marta QR chiqargansiz). Ikki marta ishlov berish - to'lov tizimi bildirishnomani yana yuborganda va siz balansni ikki marta to'laysiz yoki buyurtmani ikki marta jo'natasiz. Ular turli joylarda hal qilinadi va maqola ikkalasini ham qamrab oladi.

Kaspi-ga ulanishda olingan integratsiya hujjatlaridan so'rov formatini, imzo sarlavhasi nomini va maydonlar to'plamini oling. Quyida X-Signature, paymentId, amount kabi nomlar joy egallaydi: ularni haqiqiylari bilan almashtiring. Agar provayder bildirishnomalarni imzolamasa, buni qanday qoplash kerakligi quyida tasvirlangan.

Jadvallar

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

Qisman noyob indeks buyurtma uchun ikkinchi pending to'lovini yaratishga imkon bermaydi, hatto bir vaqtning o'zida ikkita so'rov kelib tushsa ham. Qarama-qarshilik bo'lsa, hisob-kitob kodi mavjud QR-ni qaytaradi.

Next.js da ishlov beruvchi

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

Asosiy qarorlar:

  • `webhook_events` ga yozing va bitta tranzaksiyada holatni o'zgartiring. Agar ishlov berish muvaffaqiyatsiz tugasa, voqea kaliti u bilan birga orqaga qaytariladi va qayta yetkazib berish qayta ishlanadi.
  • `FOR UPDATE` to‘lov liniyasini bloklaydi, shuning uchun ikkita parallel bildirishnoma bir vaqtning o‘zida status = 'pending' tekshiruvidan o‘tmaydi.
  • Holatga oʻtish faqat oldinga. expired dan keyin paid ga xabar berish yoki paid ni takrorlash hech narsani oʻzgartirmaydi.
  • Miqdor hisob-fakturani rasmiylashtirishda siz yozgan summa bilan tasdiqlanadi. Webhukdagi amount maydoni hech qachon haqiqat manbai sifatida ishlatilmaydi.
  • Yuk tashish, xatlar, hisob-kitoblar - protsessor ichida emas. Vazifani bir xil tranzaksiyada navbatga (yoki chiqish qutisi jadvaliga) qo'ying va uni alohida bajaring. Ishlovchi tezda javob berishi kerak, aks holda provayder etkazib berishni muvaffaqiyatsiz deb hisoblaydi va uni takrorlaydi.

Agar imzo bo'lmasa

Ba'zi integratsiyalar bildirishnomalarni imzolamaydi yoki ularni HMAC tanasidan farqli ravishda imzolamaydi. Keyin veb-hukni "to'lovni tekshirish" signali sifatida ko'rib chiqing: uni qabul qilib, identifikatoringiz yordamida provayderning API orqali statusni so'rang va faqat API javobi asosida holatni o'zgartiring. Bundan tashqari, agar provayder ularning ro'yxatini e'lon qilsa, kiruvchi manzillarni cheklang.

Umumiy xatolar

  • Imzo JSON.stringify(await req.json()) dan boshlab hisoblanadi. Tugmalar va bo'shliqlar tartibi asl nusxadan farq qiladi va imzo mos kelmaydi. Bizga asosiy matn kerak.
  • === orqali imzolarni solishtirish. Qo'ng'iroq qilishdan oldin timingSafeEqual dan foydalaning va buferlar uzunligini tekshiring, aks holda u istisno qiladi.
  • floatdagi summalar. Tiyin yoki numeric da saqlang.
  • Tranzaksiyasiz kod darajasida identifikatorlik (if (order.paid) return). Bir vaqtning o'zida ikkita so'rov paid = false ni ko'radi.

Qachon kamroq bo'lsa

Agar siz bitta toʻlovni qabul qilsangiz va buyurtmalarni qoʻlda qayta ishlasangiz, sotuvchining shaxsiy hisobidagi external_id va qoʻlda solishtiruvdan foydalangan holda noyob kalit yetarli boʻladi. Voqealar jadvali, navbat va chiqish qutisi to'lovdan so'ng avtomatik ravishda biror narsa sodir bo'lganda to'lanadi.

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

Ещё на vbcd4u.com