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

Webhook thanh toán Kaspi QR: bình thường, xác minh chữ ký và bảo vệ chống phát hành kép

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

Đầu tiên chúng ta hãy làm rõ các điều khoản

“Ghi nợ kép” và “xử lý kép” là những vấn đề khác nhau. Tiền sẽ bị ghi nợ hai lần khi hai yêu cầu thanh toán được tạo cho một đơn hàng (người mua đã nhấp vào “Thanh toán” hai lần và bạn đã phát hành QR hai lần). Xử lý kép - khi hệ thống thanh toán gửi lại thông báo và bạn tính phí số dư hai lần hoặc gửi đơn đặt hàng hai lần. Chúng được giải quyết ở những nơi khác nhau và bài viết đề cập đến cả hai.

Lấy định dạng yêu cầu, tên tiêu đề chữ ký và tập hợp các trường từ tài liệu tích hợp mà bạn nhận được khi kết nối với Kaspi. Các tên bên dưới như X-Signature, paymentId, amount là phần giữ chỗ: thay thế chúng bằng tên thực tế. Nếu nhà cung cấp không ký vào thông báo, bên dưới sẽ mô tả cách đền bù cho việc này.

Bàn

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

Chỉ mục duy nhất một phần sẽ không cho phép tạo khoản thanh toán pending thứ hai cho một đơn hàng, ngay cả khi hai yêu cầu đến cùng một lúc. Mã thanh toán trong trường hợp xung đột chỉ trả về mã QR hiện có.

Trình xử lý trong 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();
  }
}

Các quyết định quan trọng:

  • Ghi vào `webhook_events` và thay đổi trạng thái trong một giao dịch. Nếu xử lý không thành công, khóa sự kiện sẽ được khôi phục cùng với nó và quá trình phân phối lại sẽ được xử lý lại.
  • `FOR UPDATE` khóa dòng thanh toán nên hai thông báo song song sẽ không vượt qua được bước kiểm tra status = 'pending' cùng một lúc.
  • Chuyển đổi trạng thái chỉ chuyển tiếp. Thông báo paid sau expired hoặc lặp lại paid không thay đổi bất cứ điều gì.
  • Số tiền được xác nhận bằng số tiền bạn tự ghi khi xuất hóa đơn. Trường amount từ webhook không bao giờ được sử dụng làm nguồn thông tin chính xác.
  • Lô hàng, thư từ, khoản tích lũy - không nằm trong bộ xử lý. Đặt tác vụ vào hàng đợi (hoặc trong bảng hộp thư đi) trong cùng một giao dịch và thực hiện nó một cách riêng biệt. Người xử lý phải phản hồi nhanh chóng, nếu không nhà cung cấp sẽ coi việc giao hàng không thành công và lặp lại việc đó.

Nếu không có chữ ký

Một số tiện ích tích hợp không ký thông báo hoặc ký chúng khác với HMAC nội dung. Sau đó, coi webhook là tín hiệu "thanh toán bằng séc": sau khi nhận được nó, hãy yêu cầu trạng thái thông qua API của nhà cung cấp bằng cách sử dụng mã nhận dạng của bạn và chỉ thay đổi trạng thái dựa trên phản hồi của API. Ngoài ra, hãy hạn chế các địa chỉ đến nếu nhà cung cấp công bố danh sách các địa chỉ đó.

Các lỗi thường gặp

  • Chữ ký được tính từ JSON.stringify(await req.json()). Thứ tự các phím và dấu cách khác với bản gốc và chữ ký cũng không khớp. Chúng tôi cần văn bản nội dung thô.
  • So sánh chữ ký qua ===. Sử dụng timingSafeEqual và kiểm tra độ dài của bộ đệm trước khi gọi, nếu không nó sẽ đưa ra một ngoại lệ.
  • Số tiền trong float. Lưu trữ trong tiyns hoặc numeric.
  • Idempotency ở cấp mã (if (order.paid) return) không có giao dịch. Hai yêu cầu đồng thời đều sẽ thấy paid = false.

Khi ít hơn là đủ

Nếu bạn chấp nhận thanh toán một lần và xử lý đơn đặt hàng theo cách thủ công thì chỉ cần một khóa duy nhất sử dụng external_id và đối chiếu thủ công trong tài khoản cá nhân của người bán là đủ. Bảng sự kiện, hàng đợi và hộp thư đi sẽ thanh toán khi có điều gì đó tự động xảy ra sau khi thanh toán.

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

Ещё на vbcd4u.com