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

Webhook di pagamento Kaspi QR: idempotenza, verifica della firma e protezione contro la doppia emissione

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

Innanzitutto chiariamo i termini

Il “doppio addebito” e la “doppia elaborazione” sono problemi diversi. Il denaro viene addebitato due volte quando vengono create due richieste di pagamento per un ordine (l'acquirente ha fatto clic due volte su "Paga" e tu hai emesso il QR due volte). Doppia elaborazione: quando il sistema di pagamento invia nuovamente la notifica e tu addebiti il ​​saldo due volte o spedisci l'ordine due volte. Vengono risolti in luoghi diversi e l'articolo copre entrambi.

Prendi il formato della richiesta, il nome dell'intestazione della firma e la serie di campi dalla documentazione di integrazione che ricevi quando ti connetti a Kaspi. I nomi sottostanti come X-Signature, paymentId, amount sono segnaposto: sostituiscili con quelli effettivi. Se il fornitore non firma le notifiche, di seguito viene descritto come compensare ciò.

Tabelle

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

Un indice univoco parziale non consentirà la creazione di un secondo pending pagamento per un ordine, anche se due richieste arrivano contemporaneamente. Il codice di fatturazione in caso di conflitto restituisce semplicemente il QR già esistente.

Gestore in Next.js

[[VB_1_CODICE]]

Decisioni chiave:

  • Scrivi su `webhook_events` e modifica lo stato in una transazione. Se l'elaborazione fallisce, la chiave evento verrà ripristinata insieme ad essa e la riconsegna verrà elaborata nuovamente.
  • `FOR UPDATE` blocca la linea di pagamento in modo che due notifiche parallele non superino il controllo status = 'pending' contemporaneamente.
  • La transizione di stato è solo in avanti. La notifica di paid dopo expired o la ripetizione di paid non cambia nulla.
  • L'importo viene verificato con l'importo che tu stesso hai annotato al momento dell'emissione della fattura. Il campo amount di un webhook non viene mai utilizzato come fonte di verità.
  • Spedizione, lettere, ratei - non all'interno del processore. Posiziona l'attività in una coda (o in una tabella di posta in uscita) nella stessa transazione ed eseguila separatamente. L'handler deve rispondere tempestivamente, altrimenti il ​​fornitore considererà la consegna non riuscita e la ripeterà.

Se non è presente alcuna firma

Alcune integrazioni non firmano le notifiche o le firmano in modo diverso rispetto al corpo HMAC. Quindi tratta il webhook come un segnale di “assegno di pagamento”: dopo averlo ricevuto, richiedi lo stato tramite l’API del provider utilizzando il tuo identificatore e modifica lo stato solo in base alla risposta dell’API. Inoltre, limita gli indirizzi in entrata se il provider ne pubblica un elenco.

Errori comuni

  • La firma viene conteggiata da JSON.stringify(await req.json()). L'ordine delle chiavi e degli spazi è diverso dall'originale e la firma non corrisponde. Abbiamo bisogno del testo del corpo grezzo.
  • Confronto delle firme tramite ===. Usa timingSafeEqual e controlla la lunghezza dei buffer prima di chiamare, altrimenti genererà un'eccezione.
  • Importi in float. Conservare in tiyns o numeric.
  • Idempotenza a livello di codice (if (order.paid) return) senza transazione. Due richieste simultanee vedranno entrambe paid = false.

Quando meno basta

Se accetti pagamenti singoli ed elabori gli ordini manualmente, è sufficiente una chiave univoca che utilizza external_id e la riconciliazione manuale nell'account personale del venditore. La tabella degli eventi, la coda e la posta in uscita ripagano quando qualcosa accade automaticamente dopo il pagamento.

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

Ещё на vbcd4u.com