Webhook di pagamento Kaspi QR: idempotenza, verifica della firma e protezione contro la doppia emissione
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
paiddopoexpiredo la ripetizione dipaidnon cambia nulla. - L'importo viene verificato con l'importo che tu stesso hai annotato al momento dell'emissione della fattura. Il campo
amountdi 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
===. UsatimingSafeEquale controlla la lunghezza dei buffer prima di chiamare, altrimenti genererà un'eccezione. - Importi in
float. Conservare in tiyns onumeric. - Idempotenza a livello di codice (
if (order.paid) return) senza transazione. Due richieste simultanee vedranno entrambepaid = 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.