Webhook pembayaran Kaspi QR: idempotensi, verifikasi tanda tangan, dan perlindungan terhadap penerbitan ganda
Pertama, mari kita perjelas persyaratannya
“Pendebitan ganda” dan “pemrosesan ganda” adalah masalah yang berbeda. Uang didebit dua kali ketika dua permintaan pembayaran dibuat untuk satu pesanan (pembeli mengklik “Bayar” dua kali dan Anda mengeluarkan QR dua kali). Pemrosesan ganda - ketika sistem pembayaran mengirimkan pemberitahuan lagi, dan Anda menagih saldo dua kali atau mengirimkan pesanan dua kali. Mereka diselesaikan di tempat yang berbeda, dan artikel ini mencakup keduanya.
Ambil format permintaan, nama header tanda tangan, dan kumpulan bidang dari dokumentasi integrasi yang Anda terima saat menyambung ke Kaspi. Nama-nama di bawah seperti X-Signature, paymentId, amount adalah placeholder: ganti dengan yang sebenarnya. Jika penyedia tidak menandatangani pemberitahuan, di bawah ini dijelaskan cara mengkompensasinya.
Tabel
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)
);Indeks unik parsial tidak akan mengizinkan pembuatan pending-pembayaran kedua untuk sebuah pesanan, bahkan jika dua permintaan tiba pada waktu yang sama. Kode penagihan jika terjadi konflik hanya mengembalikan QR yang sudah ada.
Penangan di 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();
}
}Keputusan penting:
- Tulis ke `webhook_events` dan ubah status dalam satu transaksi. Jika pemrosesan gagal, kunci peristiwa akan dikembalikan bersamanya, dan pengiriman ulang akan diproses lagi.
- `FOR UPDATE` mengunci jalur pembayaran sehingga dua notifikasi paralel tidak akan melewati pemeriksaan
status = 'pending'secara bersamaan. - Transisi status hanya untuk maju. Memberi tahu
paidsetelahexpiredatau mengulangipaidtidak mengubah apa pun. - Jumlah tersebut diverifikasi dengan jumlah yang Anda tulis sendiri saat menerbitkan invoice. Bidang
amountdari webhook tidak pernah digunakan sebagai sumber kebenaran. - Pengiriman, surat, akrual - tidak di dalam prosesor. Tempatkan tugas dalam antrian (atau dalam tabel kotak keluar) dalam transaksi yang sama, dan jalankan secara terpisah. Penangan harus merespons dengan cepat, jika tidak, penyedia akan menganggap pengiriman tidak berhasil dan mengulanginya.
Jika tidak ada tanda tangan
Beberapa integrasi tidak menandatangani pemberitahuan atau menandatanganinya secara berbeda dari HMAC badan. Kemudian perlakukan webhook sebagai sinyal “cek pembayaran”: setelah menerimanya, minta status melalui API penyedia menggunakan pengidentifikasi Anda dan ubah status hanya berdasarkan respons API. Selain itu, batasi alamat masuk jika penyedia menerbitkan daftarnya.
Kesalahan umum
- Tanda tangan dihitung dari
JSON.stringify(await req.json()). Urutan kunci dan spasi berbeda dengan aslinya, dan tanda tangannya tidak sesuai. Kami membutuhkan teks isi mentah. - Perbandingan tanda tangan melalui
===. GunakantimingSafeEqualdan periksa panjang buffer sebelum memanggil, jika tidak maka akan muncul pengecualian. - Jumlah dalam
float. Simpan dalam tiyns ataunumeric. - Idempotensi pada level kode (
if (order.paid) return) tanpa transaksi. Dua permintaan simultan akan melihatpaid = false.
Bila lebih sedikit sudah cukup
Jika Anda menerima pembayaran tunggal dan memproses pesanan secara manual, kunci unik menggunakan external_id dan rekonsiliasi manual di akun pribadi penjual sudah cukup. Tabel event, antrian dan kotak keluar terbayar dimana sesuatu terjadi secara otomatis setelah pembayaran.