VibeFox Adyen for WooCommerce — Guida

Requisiti

WordPress: 6.0 o successivo.

WooCommerce: 7.0 o successivo, installato e attivo. Il plugin non si attiva senza di esso.

PHP: 8.0 o successivo.

Account Adyen: ti servono il nome del tuo account commerciante Adyen, una chiave API e una chiave HMAC per ogni ambiente che usi (sandbox e live) e, per i pagamenti live, il prefisso URL live. La chiave API appartiene a una credenziale API con i ruoli Checkout webservice e Merchant PAL webservice. La chiave HMAC viene generata per il webhook Standard (vedi Configurazione). La Customer Area sandbox è ca-test.adyen.com, quella live ca-live.adyen.com. Le chiavi sandbox e quelle live sono separate.

Chiave di licenza VibeFox: acquistata su vibefox.net. Una chiave funziona su un solo dominio.

Installazione

1. In WordPress vai su Plugins > Add New > Upload Plugin, scegli il file ZIP del plugin e fai clic su Install Now. Puoi anche caricare la cartella wcp_adyen_gateway in /wp-content/plugins/ via FTP.

2. Fai clic su Activate.

3. Apri le impostazioni: WooCommerce > Settings > Payments > Adyen > Manage, oppure fai clic su Settings sotto il nome del plugin nella pagina Plugin.

4. Inserisci la tua chiave di licenza VibeFox nel blocco licenza in cima alla pagina e fai clic su Activate.

5. Inserisci il tuo account commerciante, la chiave API sandbox e la chiave HMAC sandbox; più tardi, la chiave API live, la chiave HMAC live e il prefisso URL live.

6. Nella Customer Area di Adyen (sandbox e live) aggiungi un webhook Standard con l'URL mostrato nelle impostazioni del plugin (vedi Configurazione).

7. Attiva Enable/Disable. Prova un pagamento con Test mode attivo, poi deselezionalo.

Configurazione

Tutte le impostazioni si trovano in un'unica pagina: WooCommerce > Settings > Payments > Adyen. Finché le impostazioni della modalità corrente sono incomplete, la pagina mostra Adyen is hidden at checkout until the test settings are complete (oppure quelle live) ed elenca ciò che manca: Merchant account, la chiave API, la chiave HMAC e, in modalità live, Live URL prefix. Al salvataggio, una chiave HMAC non esadecimale e un prefisso URL live con caratteri diversi da lettere, cifre e trattini vengono rifiutati con un errore, e il valore precedente viene mantenuto.

Generali

Enable/Disable: Enable Adyen payment gateway attiva o disattiva il metodo di pagamento. Predefinito: disattivato.

Title: il nome del metodo di pagamento che i clienti vedono al checkout. Predefinito: Adyen.

Description: il testo mostrato sotto il metodo di pagamento al checkout. Predefinito: Pay securely via Adyen.

Account Adyen

Le chiavi API si creano nella Customer Area di Adyen in Developers > API credentials. Compila entrambi i gruppi di chiavi; l'opzione Test mode decide quale dei due viene usato.

Test mode: Use the Adyen test environment (no real money). Quando è attiva, i link di pagamento e i rimborsi vanno a checkout-test.adyen.com con la chiave API sandbox. Predefinito: attivato. Deselezionala per accettare pagamenti reali.

Merchant account: il nome del tuo account commerciante Adyen (non l'account aziendale), per esempio MyShopECOM. Di solito è lo stesso nella Customer Area sandbox e in quella live.

Credenziali sandbox

Usate quando Test mode è attivo.

Test API key: dalla Customer Area sandbox: Developers > API credentials > la tua credenziale > API key.

Test HMAC key: dalla Customer Area sandbox: Developers > Webhooks > il tuo webhook Standard > HMAC key (esadecimale). Obbligatoria: i webhook senza una firma valida vengono rifiutati.

Credenziali live

Usate quando Test mode è disattivato.

Live API key: dalla Customer Area live: Developers > API credentials > la tua credenziale > API key.

Live HMAC key: dalla Customer Area live: Developers > Webhooks > il tuo webhook Standard > HMAC key (esadecimale).

Live URL prefix: dalla Customer Area live: Developers > API URLs, per esempio 1797a841fbb37ca7-AdyenDemo da https://1797a841fbb37ca7-AdyenDemo-checkout-live.adyenpayments.com. Puoi incollare l'intero URL; il prefisso viene estratto al salvataggio.

Webhook

Gli ordini vengono segnati come pagati solo dai webhook Adyen. Nella Customer Area (sandbox e live) vai su Developers > Webhooks e aggiungi un Standard webhook con l'URL mostrato in questa sezione delle impostazioni. Ha una forma come https://your-site/wc-api/adyg_adyen_webhook/. Scegli il metodo JSON, attiva Generate HMAC key e copia la chiave in Test HMAC key o Live HMAC key. L'ambiente di ogni notifica seleziona la chiave HMAC. I webhook senza una firma valida vengono rifiutati, e Adyen li ripete più tardi. Senza il webhook, gli ordini restano Pending payment.

Il plugin gestisce questi eventi:

Gli altri eventi vengono aggiunti alle note dell'ordine. Le notifiche che non riguardano un ordine di questo negozio, per esempio il pulsante di test nella Customer Area, vengono accettate e ignorate.

Avanzate

Order status after payment: lo stato dell'ordine impostato dopo un pagamento riuscito, con un unico cambio di stato.

Debug log: Log API calls and webhook events scrive in WooCommerce > Status > Logs, origine wcp_adyen_gateway. Gli errori vengono sempre registrati. I registri non contengono mai chiavi API o HMAC né dati personali degli acquirenti. Predefinito: disattivato.

Delete data on uninstall: Delete the plugin settings and Adyen order meta (PSP references) when the plugin is deleted. Predefinito: disattivato.

Checkout

Il cliente sceglie il metodo di pagamento (per impostazione predefinita Adyen) e fa l'ordine. Il plugin crea un link di pagamento Adyen per il totale dell'ordine nella valuta dell'ordine e invia il cliente alla pagina di pagamento Adyen. Lì il cliente paga con uno qualsiasi dei metodi attivi nel tuo account Adyen. L'e-mail di fatturazione, il nome e il paese del cliente e la lingua del negozio vengono trasmessi ad Adyen, e il pagamento compare come Order # e il numero dell'ordine.

Dopo il pagamento, il cliente torna alla pagina Ordine ricevuto del tuo negozio. Il ritorno in sé non segna l'ordine come pagato: l'ordine viene segnato come pagato solo dopo che Adyen lo conferma con il webhook AUTHORISATION firmato e l'importo e la valuta corrispondono all'ordine.

Se il pagamento viene rifiutato, l'ordine diventa Failed e il cliente può riprovare. Quando il cliente avvia un nuovo pagamento per lo stesso ordine, per esempio dalla pagina Pay for order, il link di pagamento precedente scade, quindi non può essere pagato anche quello.

Se non è possibile creare il link di pagamento, il cliente vede Payment could not be initiated. Please try again or choose another payment method. Il motivo viene aggiunto alle note dell'ordine. Se le impostazioni sono incomplete, il cliente vede Payment gateway is not configured properly. Please contact the store administrator.

Per le valute senza decimali, come JPY, KRW, IDR o VND, imposta WooCommerce > Settings > General > Number of decimals a 0. Altrimenti il totale viene arrotondato all'unità intera.

Il metodo di pagamento funziona con il checkout classico e con il blocco Checkout. È compatibile con WooCommerce High-Performance Order Storage (HPOS).

Il plugin non gestisce abbonamenti o pagamenti ricorrenti, carte salvate, campi carta sul sito (Drop-in o Components), pulsanti di acquisizione o annullamento in WooCommerce né l'autenticazione di base per i webhook.

Ordini e rimborsi

Stati dell'ordine

Pending payment: il link di pagamento è stato creato e Adyen non ha ancora confermato il pagamento. La nota dell'ordine mostra il link di pagamento, l'importo e l'ambiente.

Processing, Completed or On Hold: il pagamento è stato autorizzato. Lo stato segue Order status after payment. La nota dell'ordine mostra l'importo, il PSP reference e il metodo di pagamento. L'ID transazione è il PSP reference di Adyen.

On hold after payment: Adyen ha confermato un importo o una valuta diversi dal totale dell'ordine. La nota dell'ordine mostra entrambi e l'ordine non viene segnato come pagato. Un ordine pagato viene messo in sospeso anche quando un'acquisizione non riesce, perché il denaro non è stato incassato. Verifica il pagamento nella Customer Area.

Failed: il pagamento è stato rifiutato. Gli ordini pagati, in sospeso o annullati non vengono modificati da un pagamento rifiutato.

Cancelled: il pagamento di questo ordine è stato annullato in Adyen.

Se arriva un secondo pagamento riuscito per un ordine già pagato, per esempio da un vecchio link di pagamento, l'ordine non viene modificato di nuovo. Una nota ti chiede di verificare nella Customer Area un eventuale addebito duplicato e di rimborsarlo lì, se necessario.

Rimborsi

Apri l'ordine, fai clic su Refund, inserisci l'importo e fai clic su Refund via Adyen. Sono supportati rimborsi totali e parziali. Il rimborso viene inviato all'ambiente e all'account commerciante con cui è stato effettuato il pagamento, quindi deve essere impostata la chiave API di quell'ambiente. Adyen elabora i rimborsi in modo asincrono: la richiesta viene annotata sull'ordine e l'esito finale viene aggiunto come nota dal webhook REFUND o REFUND_FAILED. Se Adyen non accetta la richiesta, WooCommerce mostra l'errore e nessun rimborso viene registrato. Con l'acquisizione manuale in Adyen, si possono rimborsare solo i pagamenti acquisiti.

I rimborsi effettuati nella Customer Area di Adyen arrivano tramite webhook e vengono aggiunti alle note dell'ordine. Non vengono registrati automaticamente come rimborsi WooCommerce.

Chiave di licenza

Il plugin funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza si trova in cima a WooCommerce > Settings > Payments > Adyen. Incolla la chiave in License key e fai clic su Activate. Il blocco mostra lo stato, per esempio la data fino alla quale la licenza è attiva e il tuo dominio. Usa Check now per verificare di nuovo lo stato, Change key per inserire un'altra chiave e Remove key per rimuoverla da questo sito. Il link Manage licenses and domains in your account apre il tuo account vibefox.net.

Una chiave funziona su un solo dominio. Rimuovere la chiave da un sito non libera il posto del dominio. Liberalo nel tuo account vibefox.net.

Senza una chiave attiva, il metodo di pagamento Adyen non viene mostrato ai clienti al checkout. Se un pagamento viene avviato comunque, il cliente vede This payment method is not available. Please choose another one. I gestori del negozio che hanno effettuato l'accesso vedono ancora il metodo di pagamento, contrassegnato da (unlicensed — visible to admins only), così puoi configurare e testare il plugin prima di acquistare una chiave. Un promemoria compare nella pagina Plugin e nelle pagine di WooCommerce. Gli ordini esistenti non sono interessati: i pagamenti già avviati vengono comunque confermati e i rimborsi funzionano.

Quando una licenza scade, il plugin continua a funzionare, ma aggiornamenti e supporto richiedono un rinnovo. Lo stato viene ricontrollato automaticamente in background.

Risoluzione dei problemi

Adyen non appare al checkout: verifica che la licenza sia attiva, che Enable/Disable sia attivo e che le impostazioni della modalità corrente siano complete: Merchant account, la chiave API e la chiave HMAC di quella modalità e, in modalità live, Live URL prefix. La pagina delle impostazioni elenca ciò che manca.

Il pagamento è andato a buon fine, ma l'ordine resta Pending payment: il webhook non funziona. Nella Customer Area dell'ambiente che usi (sandbox o live) verifica che esista il webhook Standard, che il suo URL sia esattamente quello mostrato nelle impostazioni e che il metodo sia JSON. Controlla che la chiave HMAC di quel webhook sia nel campo corrispondente (Test HMAC key o Live HMAC key). Con una chiave HMAC errata o mancante il plugin risponde HTTP 401 e Adyen ripete la consegna più tardi, quindi l'ordine si aggiorna automaticamente una volta corretta la chiave. Il registro mostra Webhook rejected: invalid HMAC signature oppure che la chiave HMAC non è configurata.

Il webhook risponde busy, retry later: l'ordine era già in elaborazione da un'altra consegna nello stesso momento. Adyen ripete automaticamente il webhook.

Errore sulla chiave HMAC al salvataggio: il campo deve contenere la chiave HMAC esadecimale della Customer Area. Il valore precedente è stato mantenuto.

Il cliente vede Payment could not be initiated: apri le note dell'ordine oppure attiva il Debug log e controlla WooCommerce > Status > Logs, origine wcp_adyen_gateway. Verifica la chiave API, l'account commerciante e, in modalità live, il prefisso URL live.

L'ordine è On hold dopo il pagamento: leggi la nota dell'ordine. L'importo o la valuta confermati da Adyen non corrispondevano all'ordine, oppure un'acquisizione non è riuscita. Può dipendere anche dall'impostazione Order status after payment.

Il rimborso non riesce: l'ordine deve avere un PSP reference Adyen, che arriva con il webhook AUTHORISATION. Devono essere impostate le credenziali dell'ambiente in cui è stato effettuato il pagamento. Con l'acquisizione manuale, si possono rimborsare solo i pagamenti acquisiti.

Il blocco licenza mostra un errore: segui il messaggio nel blocco. Per esempio, se la chiave è già usata su un altro dominio, libera un posto nel tuo account vibefox.net e fai clic su Check now. Se l'indirizzo del sito è cambiato, fai clic su Check now per attivare la chiave per il nuovo dominio. Se il server delle licenze non è raggiungibile, il plugin continua a funzionare con l'ultimo stato noto.

Disinstallazione

Disattivare il plugin mantiene tutti i dati. Per rimuoverlo, disattivalo ed eliminalo nella pagina Plugins. La chiave di licenza e lo stato della licenza di questo plugin vengono sempre rimossi. Le impostazioni del gateway e i dati Adyen salvati negli ordini (PSP reference, link di pagamento, eventi elaborati) vengono rimossi solo se Delete data on uninstall era attivo. Altrimenti restano per una successiva reinstallazione. Gli ordini esistenti mantengono le note di pagamento e gli ID transazione.

Adyen è un marchio del rispettivo titolare. Questo plugin non è affiliato né approvato da Adyen.