Integrare Adyen in Shopware 6: configurare il fornitore di pagamento

Un’unica piattaforma per carte, wallet, metodi di pagamento locali e pagamenti ai venditori di un marketplace: come installare e configurare il plugin Adyen in Shopware 6, impostare i webhook e andare live in sicurezza, anche per merchant in Italia.

Introduzione

La scelta del partner di pagamento giusto contribuisce in modo decisivo al successo di un negozio online. Adyen offre un’unica piattaforma utilizzabile in tutto il mondo per carte di credito, wallet, metodi di pagamento locali e pagamenti ai venditori di un marketplace. Questa guida accompagna merchant, sviluppatori e agenzie in Italia nell’integrazione di Adyen in Shopware 6, dal classico negozio B2C fino ai modelli marketplace con Adyen for Platforms. Scoprirà:

• come installare e configurare il plugin ufficiale di Adyen,
• come creare le credenziali API e passare dalla modalità di test a quella live,
• come attivare i metodi di pagamento e testarli a fondo,
• come gestire le notifiche asincrone tramite webhook,
• come risolvere gli errori tipici e andare live in sicurezza,
• quali regole valgono per sicurezza, compliance e prevenzione delle frodi.

Quali altri fornitori si possono collegare lo mostra la nostra panoramica sulle integrazioni di pagamento per Shopware.

Che cos'è Adyen?

Adyen è una piattaforma di pagamento con cui i merchant accettano pagamenti online, nelle app e nel punto vendita. Le caratteristiche principali:

• Metodi di pagamento globali e locali: Visa, Mastercard, American Express, Apple Pay, Google Pay e procedure regionali come iDEAL, addebito diretto SEPA, Klarna e molte altre.
• Componenti in hosting: Drop-in e Card Component acquisiscono i dati di pagamento sui server di Adyen; il Suo perimetro PCI DSS si riduce al SAQ A.
• Pagamenti ricorrenti e tokenizzazione: abbonamenti e riacquisti tramite token salvati, senza che Lei debba trattare dati delle carte.
• Prevenzione delle frodi: RevenueProtect combina regole di rischio e machine learning; 3-D Secure 2 soddisfa i requisiti dell’autenticazione forte del cliente.
• Report e analisi: tassi di autorizzazione, regolamenti e dati di tutti i canali in un unico back office.
• Marketplace: Adyen for Platforms gestisce onboarding e verifica KYC dei sub-merchant, suddivisione dei pagamenti, trattenute e pagamenti automatici.

“Un’integrazione, un’API, una piattaforma”: per i merchant Shopware con ambizioni internazionali Adyen è quindi un partner naturale. Per negozi più piccoli concentrati sul mercato italiano, Stripe, PayPal o Amazon Pay sono spesso la scelta più semplice.

Requisiti

• Shopware 6.4 o successivo, preferibilmente la versione attuale; verificare la compatibilità della versione del plugin
• PHP nella versione richiesta da Shopware con le estensioni cURL, JSON e OpenSSL
• Certificato SSL (HTTPS) sul dominio del negozio
• Account di test Adyen con profilo merchant sandbox
• Credenziali Adyen per test e live:
  • Merchant Account (ad esempio NomeAziendaCOM)
  • API key per le chiamate server to server
  • Client key per i componenti frontend, con il Suo dominio come origine consentita
  • Credenziali webhook: utente e password Basic Auth e HMAC key per verificare le notifiche in arrivo
• Account Shopware per l’installazione tramite l’amministrazione (facoltativo)
• Accesso al file system o SSH per l’installazione con Composer e per i log

Installare il plugin Adyen

Ci sono tre strade: tramite l’amministrazione, con Composer o con un caricamento manuale.

Tramite l’amministrazione

1. Apra Estensioni → Store.
2. Cerchi “Adyen” e selezioni il plugin ufficiale “Adyen Payments for Shopware 6”.
3. Lo aggiunga e, in Estensioni → Le mie estensioni, clicchi su Installa.
4. Attivi il plugin e svuoti la cache, così compariranno i nuovi metodi di pagamento.

Con Composer

cd /percorso/di/shopware
composer require adyen/adyen-shopware6
bin/console plugin:refresh
bin/console plugin:install --activate AdyenPaymentShopware6
bin/console cache:clear

Il nome tecnico esatto è indicato da bin/console plugin:list.

Caricamento manuale

Scarichi il file ZIP dal repository GitHub di Adyen e lo selezioni in Estensioni → Le mie estensioni → Carica estensione. Installi e attivi come descritto sopra.

Dopo l’attivazione trova i nuovi metodi di pagamento in Impostazioni → Negozio → Metodi di pagamento.

Configurare il plugin

Apra la configurazione del plugin Adyen dal menu contestuale dell’estensione.

Impostazioni principali

• Ambiente: inizialmente Test, in seguito Live.
• Merchant Account: il nome riportato nella Adyen Customer Area, rispettando maiuscole e minuscole.
• API key (test/live): chiave segreta per le chiamate API.
• Client key (test/live): chiave pubblica per i componenti frontend.
• Live Endpoint Prefix: il Suo prefisso univoco per l’URL live, ad esempio abcd123-checkout-live.
• Utente e password webhook: i dati Basic Auth inseriti per il webhook nella Customer Area.
• HMAC key (test/live): per verificare le firme dei webhook.

Salvi; il plugin memorizza le credenziali nella configurazione di Shopware.

Configurare i webhook

1. Nella Customer Area, in Developers → Webhooks, crei uno Standard webhook.
2. Inserisca l’URL indicato dal plugin e salvi i dati Basic Auth e la HMAC key.
3. Testi il webhook direttamente dalla Customer Area. Senza webhook funzionanti gli ordini in Shopware restano “aperti”, anche se Adyen ha autorizzato il pagamento.

Come Shopware stesso lavora con i webhook lo spiega il nostro articolo sui webhook in Shopware 6.

Funzioni opzionali

• Adyen Giving: proporre donazioni nel checkout.
• Metodi di pagamento salvati: consentire ai clienti di memorizzare le carte per l’acquisto successivo.
• Loghi dei metodi di pagamento: caricarli automaticamente da Adyen o usare immagini proprie.

Attivare i metodi di pagamento

1. Impostazioni di pagamento di Shopware: in Impostazioni → Negozio → Metodi di pagamento attivi le voci Adyen desiderate, ad esempio carta di credito, iDEAL, Klarna o metodi di pagamento salvati.
2. Canali di vendita: in Canali di vendita modifichi ogni canale storefront e aggiunga i metodi Adyen nella sezione Metodi di pagamento.
3. Adyen Customer Area: in Account → Payment methods le procedure desiderate devono essere abilitate per il Suo Merchant Account. I metodi disattivati lì non compaiono nel checkout, indipendentemente dalle impostazioni in Shopware.

Testare il checkout

Pagamenti di prova

1. Verifichi che nel plugin l’ambiente sia impostato su Test.
2. Nella storefront aggiunga un articolo al carrello e scelga un metodo di pagamento Adyen nel checkout.
3. Utilizzi le carte di test di Adyen, ad esempio Visa 4111 1111 1111 1111 con una qualsiasi data di scadenza futura e CVC 737. Carte per rifiuti, carte scadute e richieste 3-D Secure si trovano nella documentazione di Adyen.
4. Completi l’ordine. Nell’amministrazione compare inizialmente come “aperto” o “in elaborazione” e passa a “pagato” non appena arriva il webhook di Adyen.

Casi particolari

• Carta scaduta, per verificare la gestione degli errori.
• Carte di test 3-D Secure, per verificare l’autenticazione.
• Procedure con reindirizzamento come iDEAL o Klarna, per verificare il redirect e il ritorno al negozio.
• Rimborso e annullamento, affinché arrivino anche queste notifiche.

I dettagli si trovano nei log in var/log/; il plugin scrive un proprio file di log.

Passare alla modalità live

1. Nella Customer Area live generare API key, client key, credenziali webhook e HMAC key per l’esercizio live.
2. Nel plugin impostare l’ambiente su Live, inserire le credenziali live e il Live Endpoint Prefix e salvare.
3. Eseguire una transazione reale di piccolo importo e verificare che ordine e stato in Shopware siano corretti.
4. Nel back office live di Adyen controllare regolamento e consegne dei webhook.

Best practice e sicurezza

• PCI DSS: utilizzare i componenti in hosting, così i dati delle carte non toccano mai il Suo server.
• HTTPS: l’intero negozio funziona tramite SSL.
• Gestione delle chiavi: rinnovare regolarmente le API key e HMAC key, conservarle in variabili d’ambiente o in un secret store.
• Prevenzione delle frodi: attivare le regole RevenueProtect e il 3-D Secure 2 dinamico, controllare regolarmente le transazioni segnalate.
• Sicurezza dei webhook: imporre la verifica HMAC e la Basic Auth, abilitare sull’endpoint gli intervalli IP di Adyen.
• Protezione dei dati: integrare l’informativa privacy con il trattamento da parte di Adyen in conformità al GDPR e non salvare in proprio dati sensibili.
• Aggiornamenti: testare prima in staging gli aggiornamenti di plugin e Shopware, verificare nelle release notes eventuali breaking change.
• Marketplace: con Adyen for Platforms acquisire in modo sicuro i dati KYC dei venditori, gestire i pagamenti server to server e tenere separati i fondi.

Domande frequenti

Come funzionano i rimborsi?
Nel back office di Adyen come rimborso parziale o totale; i webhook aggiornano l’ordine in Shopware. Nelle versioni attuali del plugin può avviare i rimborsi anche direttamente dalla vista ordine in Shopware.

Il plugin ha un costo?
Il plugin è gratuito. Le commissioni sulle transazioni di Adyen (percentuale più importo fisso) dipendono dal Suo contratto e vengono fatturate al di fuori di Shopware, secondo il fornitore.

Posso applicare supplementi per i metodi di pagamento?
Il plugin non supporta supplementi. Nell’UE, e quindi anche in Italia, i supplementi per i comuni pagamenti con carta e SEPA non sono comunque ammessi; verifichi le regole prima di introdurre commissioni con uno sviluppo personalizzato.

Quali stati d’ordine utilizza Adyen?
Aperto (pagamento in sospeso), pagato (autorizzazione riuscita), in elaborazione (procedura asincrona o 3-D Secure in corso), fallito o annullato (rifiutato) e rimborsato.

Posso cambiare le chiavi senza interruzioni?
Sì. Generi la nuova chiave in Adyen, la inserisca nella configurazione del plugin, salvi e testi. La modifica è immediata; scelga una fascia oraria con poco traffico.

Adyen supporta il pagamento rateale?
Sì. Attivi procedure come Klarna nel Merchant Account e poi come metodo di pagamento in Shopware.

Amazon Pay o Adyen?
Amazon Pay è adatto se i Suoi clienti usano già Amazon e Lei desidera un checkout rapido con dati precompilati. Adyen è la scelta più forte per merchant internazionali con volumi elevati, metodi di pagamento locali, regolamento in più valute e prevenzione delle frodi su più negozi. Seguiamo merchant in Italia anche in questi progetti: dove il Suo checkout perde clienti lo mostra la nostra analisi del negozio; per adattamenti al processo di pagamento la supportiamo con lo sviluppo di plugin Shopware.