Perché questo può succedere e quali rischi operativi considerare
La presenza di una transazione confermata nel gateway non garantisce che WooCommerce abbia aggiornato lo stato dell’ordine o aggiunto una order note nell’ordine stesso. Questo disallineamento è frequente nelle integrazioni in cui gateway e store sono entità separate e comunicano tramite callback/webhook.
Il rischio operativo principale è l’addebito duplicato: chiedere a un cliente di ripetere il pagamento prima di aver verificato i log del gateway può generare addebiti indesiderati. Per questo il flusso di diagnostica qui descritto privilegia la raccolta di evidenze e le verifiche non distruttive prima di qualsiasi azione operativa.
Esempio: un cliente completa il checkout e il gateway mostra la transazione come “success” ma l’ordine in WooCommerce rimane in stato “in attesa” senza order note. Prima di suggerire una nuova transazione, è necessario verificare sia i log del gateway sia le order note e i log di WooCommerce. (Esempio illustrativo, senza payload reali.)
Dove cercare le prove: order note, log di WooCommerce e dashboard del gateway
Le order note sono la prima fonte di evidenza in WooCommerce: registrano eventi come messaggi dal gateway, cambi di stato o annotazioni manuali. La loro assenza, però, non prova che la transazione non esista sul gateway: servono entrambe le verifiche parallele.
Abilitate il logging del gateway e controllate WooCommerce > Status > Logs per gli eventi del giorno in cui si è verificata la transazione: i log possono contenere errori, timeout, codici di rifiuto o indizi di una mancata chiamata di callback. Parallelamente, aprite la dashboard del provider di pagamento per cercare l’ID transazione, lo stato e il timestamp corrispondente.
Non interpretate l’assenza di order note come prova definitiva di assenza di transazione: verificate i log del gateway prima di far effettuare qualunque nuova operazione al cliente.
Verificare webhook e callback: cosa controllare
Molti gateway aggiornano gli ordini tramite callback/webhook. Alcuni gateway — ad esempio Stripe — richiedono la registrazione manuale dei webhook: se il sito non riceve le chiamate webhook, l’ordine in WooCommerce può rimanere incompleto nonostante la transazione nel gateway sia riuscita.
Controlli pratici:
- Verificate nella dashboard del gateway gli eventi webhook inviati (eventi e relativi timestamp) e il loro stato di consegna.
- Controllate i log del plugin gateway su WooCommerce (abilitate il debug se non è già attivo) per vedere se il payload è arrivato e come è stato elaborato.
- Assicuratevi che l’endpoint del callback sia corretto e raggiungibile (URL pubblico, certificato TLS valido, porte e routing non bloccati dal firewall). Queste verifiche spettano anche al team hosting/DevOps quando necessario.
Non presumete che i webhook siano già configurati: controllate sempre la configurazione lato gateway.
Hook e azioni di WooCommerce coinvolte nel completamento del pagamento
Nel modello raccomandato per lo sviluppo di gateway WooCommerce, process_payment gestisce la richiesta iniziale e, quando il pagamento è confermato, l’integrazione dovrebbe chiamare $order->payment_complete() o esporre un handler callback (WC-API) che lo faccia, così che WooCommerce aggiorni stato e riduca lo stock correttamente.
Hook rilevanti includono woocommerce_pre_payment_complete, woocommerce_payment_complete e woocommerce_payment_complete_order_status_$status. Tuttavia l’esecuzione di questi hook dipende dal flusso del gateway: se la classe del gateway non è caricata nel contesto del callback, alcuni hook definiti nella classe potrebbero non essere eseguiti.
Quindi, quando un callback arriva ma non si vedono order note o stato aggiornato, verificate che l’handler WC-API sia stato chiamato e che il codice del gateway invochi effettivamente payment_complete() nel contesto del callback.
Riprodurre il problema in sicurezza: staging, logging e test order
Per diagnosticare senza compromettere dati reali:
- Abilitate il debug/logging nel plugin gateway e in WooCommerce prima di generare altri eventi; i log cattureranno le nuove transazioni solo dopo l’abilitazione.
- Se possibile, riproducete il flusso in un ambiente di staging isolato con il gateway in modalità sandbox. Evitate test in produzione che possano generare addebiti reali.
- Per isolare conflitti, disattivate tutti i plugin non essenziali e il tema sulla copia di staging, lasciando attivi solo WooCommerce e il/i gateway; eseguite un ordine di prova e riattivate i componenti uno a uno per identificare il responsabile.
Attenzione: non eseguite disattivazioni massicce di plugin su produzione senza staging: c’è rischio di downtime o perdita di funzionalità. E non chiedete al cliente di riprovare il pagamento prima di aver verificato i log del gateway per evitare addebiti duplicati.
Checklist diagnostica passo‑passo (non distruttiva)
- Raccogliere elementi identificativi dell’ordine: ID ordine WooCommerce, timestamp, email cliente, importo visualizzato in checkout.
- Controllare le order note nell’ordine su WooCommerce per voci relative al gateway o al callback.
- Abilitare logging nel plugin gateway e in WooCommerce se non già attivo; scaricare i log del giorno/ora della transazione.
- Cercare l’ID transazione o il timestamp nella dashboard del gateway; verificare lo stato e gli eventi webhook inviati.
- Se il gateway mostra un webhook inviato al vostro sito, controllare che l’endpoint abbia risposto con 200 OK e che il plugin abbia processato il payload.
- Se non ci sono webhook o la dashboard mostra fallimenti di consegna, coinvolgere DevOps/hosting per verificare raggiungibilità/SSL/firewall.
- Se il webhook è stato ricevuto ma WooCommerce non ha aggiornato l’ordine, verificare che l’handler WC-API abbia eseguito $order->payment_complete() o l’azione equivalente; controllare eventuali errori nei log PHP/servidore.
- Se sospettate conflitto plugin/tema, riprodurre in staging disattivando i plugin non essenziali e riattivarli uno a uno per isolare.
- Fermarsi prima di qualsiasi azione che possa creare addebiti o rimborsi: non chiedere al cliente di ripetere il pagamento senza aver prima riconciliato i log del gateway.
Casi speciali da considerare: total mismatch e Order Withdrawal (WooCommerce 11.1)
WooCommerce 11.1 introduce controlli di consistenza nel checkout a blocchi: se il totale finale è aumentato rispetto a quello mostrato al cliente (total mismatch), la creazione dell’ordine può essere bloccata intenzionalmente — questo è un comportamento voluto e non un bug di comunicazione con il gateway.
La funzionalità Order Withdrawal aggiunge una pagina per richieste di recesso che, se i dati coincidono, collega la richiesta all’ordine aggiungendo una order note; l’invio non cambia automaticamente lo stato dell’ordine né esegue rimborsi: queste rimangono azioni manuali del merchant.
Non confondete quindi l’assenza di aggiornamento di stato dovuta a controlli di consistenza o a Order Withdrawal con una mancata comunicazione del gateway: entrambi possono generare order note o blocchi con cause diverse.
Cosa comunicare al cliente e operazioni sicure lato merchant
Modello operativo: spiegate al cliente che state verificando i log del gateway e di WooCommerce e che, per evitare addebiti duplicati, non gli chiederete di ripetere il pagamento finché non avrete conferma dal provider di pagamento. Se emerge che la transazione è stata processata ma WooCommerce non l’ha registrata, indicate che il merchant eseguirà la riconciliazione interna prima di proporre rimborso o completamento manuale.
Segnalazione al team tecnico: cosa includere nel ticket
Quando aprite un ticket per sviluppatori o hosting, includete sempre:
- ID ordine, ID transazione gateway (se disponibile) e timestamp;
- estratti dei log WooCommerce e del plugin gateway relativi all’evento;
- eventi webhook e il loro esito dalla dashboard del gateway;
- passi per riprodurre in staging e indicazione se il problema è stato riprodotto lì.
DevOps dovrebbe verificare la raggiungibilità dell’endpoint e i log server; lo sviluppatore gateway dovrebbe controllare che l’handler callback chiami payment_complete() nel contesto corretto.
Risorse ufficiali e letture consigliate
– Troubleshooting Orders — documentazione ufficiale WooCommerce.
– Payment Gateway API — documentazione per sviluppatori su process_payment, callback e payment_complete.
– Note di rilascio e post sul blog su WooCommerce 11.1: Order Withdrawal e total mismatch.
Conclusione e prossimi passi consigliati
Sequenza operativa raccomandata: abilitare logging, raccogliere order note e log gateway, verificare webhook e endpoint, riprodurre in staging con gateway in sandbox e isolare plugin/tema per identificare conflitti. Fermatevi prima di chiedere ripetizioni di pagamento o di eseguire rimborsi fino a quando la riconciliazione non conferma lo stato finanziario reale della transazione.
Seguendo questa procedura potrete identificare la causa del disallineamento minimizzando i rischi operativi e disponendo delle evidenze necessarie per azioni manuali sicure.