Calitatea hostingului dă valoare site-ului tău.

Magazine online și integrări · Ghid practic

Webhookuri de plată: confirmă tranzacția fără comenzi duplicate

Plățile și notificările pot continua după ce clientul părăsește checkout-ul, iar procesatorii pot retrimite același webhook. Un handler sigur verifică semnătura, salvează evenimentul și aplică efectele o singură dată.

Folosește eveniment server-side pentru rezultatul plății

O pagină de succes din browser nu este confirmarea de încredere pentru server. Clientul poate închide fila, conexiunea se poate întrerupe sau un utilizator poate apela direct ruta de întoarcere. Configurează procesatorul să trimită evenimentele necesare către un endpoint HTTPS și verifică starea obiectului de plată cu API-ul dacă payloadul nu conține date suficiente.

Plățile pot avea pași suplimentari de autentificare și metode cu rezultat asincron. O stare „processing” nu este egală cu „succeeded”; conectează notificările de succes, eșec sau confirmare întârziată la o tranziție clară a comenzii. Pornește fulfillmentul numai după condiția de plată pe care ai definit-o.

Păstrează ID-ul procesatorului și ID-ul intern al coșului/comenzii într-o mapare stabilă. Asta îți permite să investighezi o plată care există la procesator, dar lipsește din magazin, fără să inițiezi încă o debitare.

Verifică semnătura și protejează endpointul

Verifică semnătura criptografică folosind corpul brut al cererii și secretul endpointului sau endpointul oficial de verificare al procesatorului. Parsarea și reserializarea JSON-ului înainte de calcul poate schimba octeții și invalida verificarea. Folosește HTTPS în producție și ține secretul în configurație protejată, nu în codul public ori într-un URL.

După autentificarea mesajului, validează contul, mediul și tipul evenimentului. Un eveniment sandbox nu trebuie să actualizeze o comandă live. Loghează referința și rezultatul verificării, însă redactează datele personale, tokenurile și detaliile care nu sunt necesare depanării.

Rotește secretele cu procedura furnizorului și testează perioada de tranziție. Dacă mai multe endpointuri ori aplicații primesc același eveniment, păstrează separat ID-ul abonamentului/livrării și ID-ul acțiunii comerciale pentru corelare.

Fă handlerul idempotent și rezistent la retry

Webhookurile pot fi livrate din nou după timeout, cod HTTP de eroare sau problemă de rețea. Înregistrează ID-ul evenimentului într-un depozit durabil cu unicitate și verifică dacă a fost procesat deja. În cazul unui duplicat, răspunde cu succes fără să creezi o a doua comandă, expediere, captură sau rambursare.

Pentru cererile de creare/modificare trimise către API-ul procesatorului, folosește o cheie de idempotency stabilă pentru aceeași operațiune și aceiași parametri. Dacă nu primești răspuns, nu genera imediat o cheie nouă: interoghează starea primei operațiuni sau repetă în siguranță cu cheia existentă.

Răspunde rapid după ce evenimentul a fost verificat și salvat, apoi mută operațiile lente într-o coadă. Workerul trebuie să confirme efectele externe și să poată relua jobul fără să aplice același efect de două ori. Un jurnal de încercări și o coadă de erori permit recuperarea controlată.

Monitorizează livrările și reconciliază plățile

Urmărește codurile HTTP, numărul de retry-uri, latența endpointului și subscripțiile dezactivate. Fiecare procesator are propria politică de retry; consultă dashboardul și recuperează evenimentele ratate după remediere. Pentru operațiunile importante, nu presupune că retrimiterea automată va continua la nesfârșit.

Rulează periodic o reconciliere între comenzile locale și tranzacțiile procesatorului, folosind ID, sumă, monedă și status. Identifică tranzacții fără comandă și comenzi cu status desincronizat. Nu rambursa și nu încasa manual înainte de a confirma operațiunea reală în sistemul sursă.

Testează cu scenarii: semnătură greșită, același webhook de două ori, timeout după procesare dar înainte de răspuns, plată întârziată și eșec ulterior. Păstrează aceste teste la fiecare schimbare a endpointului. Astfel, integrarea rămâne controlabilă chiar dacă procesatorul repetă livrarea sau browserul clientului nu revine.

Întrebări frecvente

De ce nu ar trebui să mă bazez doar pe pagina de succes din checkout?

Clientul poate să nu revină în browser, iar unele metode se confirmă asincron. Confirmă plata server-side prin procesator și eveniment webhook validat.

Cum împiedic un webhook retrimis să creeze două expedieri?

Salvează ID-ul livrării/evenimentului și procesează-l idempotent, verificând dacă efectul a fost deja aplicat. Răspunde cu succes la duplicat.

Ce fac dacă webhookul nu ajunge la server?

Verifică HTTPS, disponibilitatea endpointului, codurile de răspuns și logul retry-urilor din dashboardul procesatorului. După remediere, recreează subscripția dacă a fost dezactivată și reconciliază intervalul lipsă.

Surse și documentare

Explicație editorială generală, bazată pe documentația de mai jos. Configurația concretă și condițiile furnizorului pot diferi. Documentare: 22 noiembrie 2026.