Webhook płatności Kaspi QR: idempotencja, weryfikacja podpisu i ochrona przed podwójnym wydaniem
Najpierw wyjaśnijmy warunki
„Podwójne obciążenie” i „podwójne przetwarzanie” to różne problemy. Pieniądze są pobierane dwukrotnie, gdy dla jednego zamówienia utworzone zostaną dwa żądania płatności (kupujący dwukrotnie kliknął „Zapłać”, a Ty dwukrotnie wystawiłeś kod QR). Podwójne przetwarzanie - gdy system płatności ponownie wyśle powiadomienie, a Ty dwukrotnie obciążysz saldo lub dwukrotnie wyślesz zamówienie. Są one rozwiązywane w różnych miejscach, a artykuł omawia oba.
Weź format żądania, nazwę nagłówka podpisu i zestaw pól z dokumentacji integracji, którą otrzymasz podczas łączenia się z Kaspi. Poniższe nazwy, takie jak X-Signature, paymentId, amount są symbolami zastępczymi: zastąp je rzeczywistymi. Jeśli dostawca nie podpisze powiadomień, poniżej opisano, jak to zrekompensować.
Tabele
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)
);Częściowy unikalny indeks nie pozwoli na utworzenie drugiej pending-płatności za zamówienie, nawet jeśli w tym samym czasie nadejdą dwa żądania. Kod rozliczeniowy w przypadku konfliktu po prostu zwraca już istniejący kod QR.
Obsługa w Next.js
[[VB_1_KOD]]
Kluczowe decyzje:
- Napisz do `webhook_events` i zmień status w jednej transakcji. Jeśli przetwarzanie się nie powiedzie, klucz zdarzenia zostanie wycofany wraz z nim, a ponowna dostawa zostanie zrealizowana ponownie.
- `FOR UPDATE` blokuje linię płatniczą, dzięki czemu dwa równoległe powiadomienia nie przejdą kontroli
status = 'pending'w tym samym czasie. - Przejście stanu następuje tylko w przód. Powiadomienie
paidpoexpiredlub powtórzeniepaidniczego nie zmienia. - Kwota jest weryfikowana z kwotą, którą sam wpisałeś przy wystawieniu faktury. Pole
amountwebhooka nigdy nie jest używane jako źródło prawdy. - Przesyłki, listy, rozliczenia międzyokresowe – nie wewnątrz procesora. Umieść zadanie w kolejce (lub w tabeli skrzynek nadawczych) w tej samej transakcji i wykonaj je osobno. Osoba obsługująca musi zareagować szybko, w przeciwnym razie dostawca uzna dostawę za nieudaną i powtórzy ją.
Jeśli nie ma podpisu
Niektóre integracje nie podpisują powiadomień lub podpisują je inaczej niż ciało HMAC. Następnie potraktuj webhooka jako sygnał „płatności czekiem”: po jego otrzymaniu zapytaj o status poprzez API dostawcy przy użyciu swojego identyfikatora i zmień status dopiero na podstawie odpowiedzi API. Dodatkowo ogranicz adresy przychodzące, jeśli dostawca publikuje ich listę.
Typowe błędy
- Podpis liczony jest od
JSON.stringify(await req.json()). Kolejność klawiszy i spacji jest inna niż oryginalna, a podpis nie jest zgodny. Potrzebujemy surowego tekstu podstawowego. - Porównanie podpisów poprzez
===. UżyjtimingSafeEquali sprawdź długość buforów przed wywołaniem, w przeciwnym razie zgłosi wyjątek. - Kwoty w
float. Przechowuj w tiyns lubnumeric. - Idempotencja na poziomie kodu (
if (order.paid) return) bez transakcji. W przypadku dwóch jednoczesnych żądań zostanie wyświetlony komunikatpaid = false.
Kiedy wystarczy mniej
Jeśli akceptujesz płatności jednorazowe i realizujesz zamówienia ręcznie, wystarczy unikalny klucz przy użyciu external_id i ręczne uzgodnienie na koncie osobistym sprzedawcy. Tabela zdarzeń, kolejka i skrzynka nadawcza opłacają się, gdy coś dzieje się automatycznie po dokonaniu płatności.