कास्पि क्यूआर भुगतान वेबहुक: निष्क्रियता, हस्ताक्षर सत्यापन और दोहरे जारी करने से सुरक्षा
सबसे पहले, आइए शर्तों को स्पष्ट करें
"डबल डेबिटिंग" और "डबल प्रोसेसिंग" अलग-अलग समस्याएं हैं। जब एक ऑर्डर के लिए दो भुगतान अनुरोध बनाए जाते हैं तो पैसा दो बार डेबिट किया जाता है (खरीदार ने दो बार "भुगतान करें" पर क्लिक किया और आपने दो बार क्यूआर जारी किया)। दोहरी प्रोसेसिंग - जब भुगतान प्रणाली दोबारा अधिसूचना भेजती है, और आप शेष राशि का दो बार शुल्क लेते हैं या ऑर्डर को दो बार शिप करते हैं। उन्हें अलग-अलग जगहों पर हल किया गया है और लेख में दोनों को शामिल किया गया है।
कास्पी से कनेक्ट होने पर आपको प्राप्त होने वाले एकीकरण दस्तावेज़ से अनुरोध प्रारूप, हस्ताक्षर हेडर नाम और फ़ील्ड का सेट लें। नीचे दिए गए नाम जैसे 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-भुगतान करने की अनुमति नहीं देगा, भले ही दो अनुरोध एक ही समय में आएं। विरोध की स्थिति में बिलिंग कोड केवल पहले से मौजूद क्यूआर लौटाता है।
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को दोहराने से कुछ भी नहीं बदलता है। - राशि का सत्यापन उस राशि से किया जाता है जिसे आपने चालान जारी करते समय स्वयं लिखा था। वेबहुक से
amountफ़ील्ड का उपयोग कभी भी सत्य के स्रोत के रूप में नहीं किया जाता है। - शिपमेंट, पत्र, उपार्जन - प्रोसेसर के अंदर नहीं। कार्य को एक ही लेन-देन में एक कतार में (या आउटबॉक्स तालिका में) रखें, और इसे अलग से निष्पादित करें। हैंडलर को तुरंत प्रतिक्रिया देनी होगी, अन्यथा प्रदाता डिलीवरी को असफल मान लेगा और इसे दोहराएगा।
यदि कोई हस्ताक्षर नहीं है
कुछ एकीकरण सूचनाओं पर हस्ताक्षर नहीं करते हैं या उन्हें बॉडी एचएमएसी से अलग तरीके से हस्ताक्षरित करते हैं। फिर वेबहुक को "चेक भुगतान" सिग्नल के रूप में मानें: इसे प्राप्त करने के बाद, अपने पहचानकर्ता का उपयोग करके प्रदाता के एपीआई के माध्यम से स्थिति का अनुरोध करें और केवल एपीआई प्रतिक्रिया के आधार पर स्थिति बदलें। इसके अतिरिक्त, यदि प्रदाता उनकी सूची प्रकाशित करता है तो आने वाले पतों को सीमित करें।
सामान्य त्रुटियाँ
- हस्ताक्षर की गिनती
JSON.stringify(await req.json())से की जाती है। कुंजियों और रिक्त स्थानों का क्रम मूल से भिन्न है, और हस्ताक्षर मेल नहीं खाते हैं। हमें कच्चे मुख्य पाठ की आवश्यकता है। ===के माध्यम से हस्ताक्षरों की तुलना।timingSafeEqualका उपयोग करें और कॉल करने से पहले बफ़र्स की लंबाई जांचें, अन्यथा यह एक अपवाद फेंक देगा।floatमें राशियाँ। टिएन याnumericमें स्टोर करें।- लेनदेन के बिना कोड स्तर (
if (order.paid) return) पर निष्क्रियता। एक साथ दो अनुरोधों परpaid = falseदिखाई देगा।
जब कम ही काफी हो
यदि आप एकल भुगतान स्वीकार करते हैं और आदेशों को मैन्युअल रूप से संसाधित करते हैं, तो external_id का उपयोग करने वाली एक अद्वितीय कुंजी और विक्रेता के व्यक्तिगत खाते में मैन्युअल समाधान पर्याप्त है। ईवेंट तालिका, कतार और आउटबॉक्स भुगतान करते हैं जहां भुगतान के बाद कुछ स्वचालित रूप से होता है।