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

Webhook płatności Kaspi QR: idempotencja, weryfikacja podpisu i ochrona przed podwójnym wydaniem

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

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 paid po expired lub powtórzenie paid niczego nie zmienia.
  • Kwota jest weryfikowana z kwotą, którą sam wpisałeś przy wystawieniu faktury. Pole amount webhooka 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żyj timingSafeEqual i sprawdź długość buforów przed wywołaniem, w przeciwnym razie zgłosi wyjątek.
  • Kwoty w float. Przechowuj w tiyns lub numeric.
  • Idempotencja na poziomie kodu (if (order.paid) return) bez transakcji. W przypadku dwóch jednoczesnych żądań zostanie wyświetlony komunikat paid = 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.

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

Ещё на vbcd4u.com