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

Kaspi QR 支付 webhook:幂等性、签名验证和防止双重发行

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

首先,让我们澄清一下术语

“双重借记”和“双重处理”是不同的问题。当为一个订单创建两个付款请求时(买家点击“付款”两次并且您发出二维码两次),钱会被扣除两次。双重处理-当支付系统再次发送通知时,您两次收取余额或两次发货订单。它们在不同的地方得到解决,本文涵盖了两者。

从连接到 Kaspi 时收到的集成文档中获取请求格式、签名标头名称和字段集。下面的名称如 X-Signature、paymentId、amount 是占位符:将其替换为实际名称。如果提供商未签署通知,下面描述了如何对此进行补偿。

表格

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

即使两个请求同时到达,部分唯一索引也不允许为订单创建第二个 pending 付款。如果发生冲突,计费代码只会返回已经存在的 QR。

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

关键决策:

  • 写入`webhook_events`并在一笔事务中更改状态。如果处理失败,事件密钥将随之回滚,并重新处理重新传递。
  • `FOR UPDATE` 锁定支付线,因此两个并行通知不会同时通过 status = 'pending' 检查。
  • 状态转换仅向前。 在 expired 之后通知 paid 或重复 paid 不会改变任何内容。
  • 金额经核实与您开具发票时自己记下的金额一致。 Webhook 中的 amount 字段永远不会用作事实来源。
  • 发货、信件、应计费用 - 不在处理器内。将任务放入同一事务中的队列(或发件箱表)中,并单独执行。处理者必须快速响应,否则提供商将认为交付不成功并重复交付。

如果没有签名

某些集成不会对通知进行签名,或者对通知进行与正文 HMAC 不同的签名。然后将 Webhook 视为“检查付款”信号:收到该信号后,使用您的标识符通过提供商的 API 请求状态,并仅根据 API 响应更改状态。此外,如果提供商发布了传入地址列表,请限制传入地址。

常见错误

  • 签名从JSON.stringify(await req.json())开始计数。键和空格的顺序与原来不同,签名也不匹配。我们需要原始正文。
  • 通过===比较签名。使用timingSafeEqual并在调用之前检查缓冲区的长度,否则会抛出异常。
  • float 中的金额。存储在 tiyns 或 numeric 中。
  • 代码级别(if (order.paid) return)的幂等性,无需事务。两个同时请求都会看到 paid = false。

当更少就足够了

如果您接受单笔付款并手动处理订单,则使用 external_id 的唯一密钥和卖家个人帐户中的手动对账就足够了。事件表、队列和发件箱在付款后自动发生的情况下进行支付。

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

Ещё на vbcd4u.com