Gateway di pagamento WooCommerce: scegliere, configurare e non perdere ordini

Il gateway di pagamento è il cuore dell'e-commerce — e il punto dove vediamo più errori. Un gateway mal configurato non dà errori visibili: il cliente paga, l'ordine risulta in sospeso, il denaro arriva ma WooCommerce non lo registra come completato. Risultato: il cliente pensa di aver pagato, il commerciante non vede l'ordine, e il prodotto non viene spedito. È il problema più costoso e più silenzioso di WooCommerce, e quasi sempre è una questione di webhook non configurati o non raggiungibili.

La scelta del gateway non è solo una questione di commissioni. Le commissioni di Stripe (1.5% + 0.25€) o PayPal (3.4% + 0.35€) sono visibili, ma i costi nascosti sono quelli che pesano: i chargeback (20€ per contestazione), i refund (spesso a pagamento), i tempi di accredito (2-7 giorni lavorativi), e la disponibilità del supporto tecnico quando qualcosa va storto. Un gateway con commissioni basse ma supporto inesistente ti costa di più in tempo perso quando un pagamento non arriva.

Webhook: il motivo per cui gli ordini risultano in sospeso

Il problema più comune con i gateway di pagamento è l'ordine che resta 'In attesa di pagamento' anche se il cliente ha pagato. La causa quasi sempre è il webhook. Un webhook è una notifica che il gateway invia al tuo WooCommerce quando un pagamento viene completato — ma se il webhook non arriva o non viene processato, WooCommerce non sa che il pagamento è andato a buon fine. Ecco come verificare e configurare i webhook:

<?php
// Logging dei webhook per diagnosticare ordini in sospeso
add_action( 'woocommerce_api_wc_gateway_stripe', function() {
    // Registra ogni webhook ricevuto per diagnosticare
    $payload = file_get_contents( 'php://input' );
    $event   = json_decode( $payload, true );

    if ( $event ) {
        error_log( sprintf(
            '[Stripe Webhook] type=%s order_id=%s status=%s',
            $event['type'] ?? 'unknown',
            $event['data']['object']['metadata']['order_id'] ?? 'n/a',
            $event['data']['object']['status'] ?? 'n/a'
        ) );
    }
} );

// Verifica che i webhook di WooCommerce siano raggiungibili
// L'URL del webhook è: https://example.com/?wc-api=wc_gateway_stripe
// Testa con curl:
// curl -X POST https://example.com/?wc-api=wc_gateway_stripe \
//   -H 'Content-Type: application/json' \
//   -d '{"type":"ping"}'
// Deve restituire 200 OK, non 404 o 500

// Se i webhook non arrivano, possibili cause:
// 1. Firewall/WAF che blocca le richieste del gateway
// 2. HTTPS non valido (certificato scaduto o self-signed)
// 3. Plugin di sicurezza che blocca /?wc-api=*
// 4. Page cache che serve una versione cachata del webhook
// 5. wp-cron disabilitato senza cron di sistema (i webhook usano wp-cron)

Stripe vs PayPal vs gateway italiani: cosa scegliere

La scelta del gateway dipende dal mercato, dal volume, e dal tipo di prodotti. Stripe è la scelta migliore per la maggior parte degli e-commerce: commissioni basse (1.5% + 0.25€ per carte europee), integrazione eccellente con WooCommerce, supporto a Apple Pay/Google Pay, e un dashboard chiaro. PayPal è necessario come metodo aggiuntivo (molti clienti lo vogliono), ma le commissioni sono più alte (3.4% + 0.35€) e i chargeback sono più facili per il cliente.

Per il mercato italiano, i gateway come SumUp, Nexi o Axerve offrono commissioni competitive e supporto in italiano — importante quando qualcosa va storto. La differenza tra un gateway con supporto 24/7 in italiano e uno con supporto via email in inglese si sente quando un pagamento non arriva il venerdì sera prima di un weekend di saldi.

Refund e chargeback: gestire i rimborsi senza perdere il controllo

I refund (rimborsi volontari) e i chargeback (controversie initiate dal cliente tramite la banca) sono due cose diverse che vanno gestite diversamente. Il refund lo fai tu da WooCommerce — e deve sincronizzarsi con il gateway. Il chargeback arriva dal gateway e tu devi rispondere con le prove della transazione. Ecco come gestire entrambi:

<?php
// Gestione refund automatica via gateway
add_action( 'woocommerce_order_refunded', function( $order_id, $refund_id ) {
    $order  = wc_get_order( $order_id );
    $refund = wc_get_order( $refund_id );

    $payment_method = $order->get_payment_method();

    // Per Stripe, il refund viene gestito dal plugin automaticamente
    // Ma verifica che sia andato a buon fine:
    if ( 'stripe' === $payment_method ) {
        $refund_processed = $refund->get_meta( '_stripe_refund_id' );
        if ( ! $refund_processed ) {
            // Il refund non è stato processato da Stripe — avvisa l'admin
            $order->add_order_note(
                'ATTENZIONE: refund non processato dal gateway. Verificare manualmente su Stripe Dashboard.'
            );
            wp_mail(
                get_option( 'admin_email' ),
                'Refund non processato — Ordine #' . $order_id,
                'Il refund per l\'ordine #' . $order_id .
                ' non è stato processato da Stripe.'
            );
        }
    }
}, 10, 2 );

// Gestione chargeback: avvisa l'admin quando arriva
add_action( 'woocommerce_order_status_on_hold', function( $order_id ) {
    $order = wc_get_order( $order_id );
    if ( $order->get_meta( '_stripe_charge_disputed' ) ) {
        wp_mail(
            get_option( 'admin_email' ),
            'CHARGEBACK ricevuto — Ordine #' . $order_id,
            'È stato ricevuto un chargeback per l\'ordine #' . $order_id .
            '. Accedi alla dashboard del gateway per rispondere con le prove.'
        );
    }
} );

Il test: verifica il gateway prima di andare in produzione

Prima di aprire un e-commerce, testa il gateway end-to-end in sandbox. Completa un ordine con una carta di test, verifica che l'ordine risulti completato in WooCommerce, che l'email di conferma parta, e che il webhook sia registrato. Poi testa un refund e verifica che venga processato. Questi test prendono 15 minuti e prevengono il problema più costoso: ordini pagati ma non registrati.

Il gateway di pagamento è l'infrastruttura più delicata dell'e-commerce. Non è dove si risparmia — è dove si investe in configurazione corretta, webhook testati, e monitoraggio. Un gateway mal configurato è un problema silenzioso che si manifesta nel momento peggiore: il giorno dei saldi, quando il volume di ordini è alto e ogni ordine perso è fatturato perso. La configurazione corretta è il lavoro di un'ora che protegge mesi di vendite.