VibeFox Adyen for PrestaShop — Guida

Requisiti

PrestaShop: da 8.0 a 9.x.

PHP: 8.0 o successivo. Il modulo non si installa su versioni precedenti di PHP.

Account Adyen: ti servono il nome del tuo account commerciante Adyen, una chiave API e una chiave HMAC per ciascun ambiente che usi (test 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). L'area clienti di test è ca-test.adyen.com, quella live è ca-live.adyen.com. Le chiavi di test e quelle live sono separate. Non serve una chiave client, perché la pagina di pagamento è ospitata da Adyen.

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

Installazione

1. Nel back office vai su Modules > Module Manager e fai clic su Upload a module. Scegli il file ZIP del modulo.

2. Al termine del caricamento fai clic su Configure, oppure trova più tardi VibeFox Adyen Gateway nell'elenco dei moduli e fai clic su Configure.

3. Inserisci la tua chiave di licenza VibeFox in License key, nel blocco licenza in alto nella pagina di configurazione del modulo, e fai clic su Activate (vedi Chiave di licenza).

4. Inserisci il tuo account commerciante, la chiave API di test e la chiave HMAC di test, e più tardi la chiave API live, la chiave HMAC live e il prefisso URL live.

5. Nell'area clienti Adyen (test e live) aggiungi un webhook Standard con l'URL mostrato nella sezione Webhook del modulo (vedi Configurazione).

6. Attiva Enable/Disable e fai clic su Save. Prova un pagamento con Test mode attivo, poi disattivalo.

All'installazione il modulo crea lo stato dell'ordine Adyen payment on hold. PrestaShop attiva il modulo di pagamento per le valute, i paesi e i gruppi di clienti attivi in quel momento. Controllali e modificali in Payment > Preferences; i paesi che aggiungi in seguito devono essere selezionati lì.

Configurazione

Tutte le impostazioni si trovano nella pagina del modulo: Modules > Module Manager > VibeFox Adyen Gateway > Configure. Ogni sezione ha un proprio pulsante Save, che salva l'intera pagina. Finché le impostazioni della modalità corrente sono incomplete, la pagina mostra Adyen is hidden at checkout until the test settings are complete (o le impostazioni live) ed elenca ciò che manca: Merchant account, la chiave API, la chiave HMAC e, in modalità live, Live URL prefix. Mentre Test mode è attivo, la pagina mostra Test mode is on: payment links and refunds go to the Adyen test environment, no real money. Al salvataggio, una chiave HMAC non esadecimale e un prefisso URL live con caratteri diversi da lettere, cifre e trattini non vengono salvati: un avviso indica il campo e resta il valore precedente.

Adyen

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. È anche il nome del metodo di pagamento salvato nell'ordine. Predefinito: Adyen. Obbligatorio.

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

Account Adyen

Le chiavi API si creano nell'area clienti Adyen, in Developers > API credentials. Compila entrambi i set di chiavi; l'interruttore Test mode seleziona quale viene usato.

Test mode: usa l'ambiente di test di Adyen (nessun denaro reale). Quando è attivo, i link di pagamento e i rimborsi vanno a checkout-test.adyen.com con la chiave API di test. Predefinito: attivo. Disattivalo per accettare pagamenti reali. Finché è attivo, i clienti vedono Test mode: no real payment is taken. sotto il metodo di pagamento.

Merchant account: il nome del tuo account commerciante Adyen (non l'account aziendale), per esempio MyShopECOM. Di solito è lo stesso nell'area clienti di test e in quella live.

Credenziali di test

Usate mentre Test mode è attivo.

Test API key: dall'area clienti di test: Developers > API credentials > la tua credenziale > API key.

Test HMAC key: dall'area clienti di test: Developers > Webhooks > il tuo webhook Standard > HMAC key (esadecimale). Obbligatoria: i webhook senza firma valida vengono rifiutati.

Credenziali live

Usate quando Test mode è disattivato.

Live API key: dall'area clienti live: Developers > API credentials > la tua credenziale > API key.

Live HMAC key: dall'area clienti live: Developers > Webhooks > il tuo webhook Standard > HMAC key (esadecimale).

Live URL prefix: dall'area clienti live: Developers > API URLs, per esempio 1797a841fbb37ca7-AdyenDemo da https://1797a841fbb37ca7-AdyenDemo-checkout-live.adyenpayments.com. Puoi incollare l'URL completo; il prefisso viene ricavato da esso al salvataggio.

Le chiavi API e HMAC salvate non vengono mostrate di nuovo. Il campo resta vuoto e il suo suggerimento termina con Saved — leave empty to keep it. Inserisci un nuovo valore solo per cambiarlo.

Clear saved secrets: seleziona una chiave e fai clic su Save per rimuoverla. Un campo vuoto mantiene il valore salvato.

Webhook

Gli ordini vengono creati solo dai webhook Adyen. Nell'area clienti (test e live) vai su Developers > Webhooks e aggiungi un Standard webhook con l'URL mostrato in Webhook URL in questa sezione. Con gli URL parlanti ha questo aspetto: https://your-shop/module/wcp_adyen_gateway/webhook, eventualmente con un codice lingua come /en/. Copia l'URL esattamente come lo mostrano le impostazioni, perché Adyen non segue i reindirizzamenti. Scegli il formato 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, e una notifica viene applicata solo a un link di pagamento creato nello stesso ambiente e con lo stesso account commerciante. Una notifica di test non conferma mai un pagamento live. I webhook senza firma valida vengono rifiutati con HTTP 401, e Adyen li riprova più tardi. Senza webhook non viene creato alcun ordine.

Il modulo gestisce questi eventi:

Gli altri eventi vengono aggiunti alle note dell'ordine. Le notifiche che non riguardano un carrello di questo negozio, per esempio il pulsante di test nell'area clienti, vengono accettate e ignorate. Il webhook funziona mentre il negozio è in manutenzione e non è bloccato dalla restrizione per paese del tuo negozio.

Avanzate

Order status after payment: lo stato dell'ordine impostato da un webhook AUTHORISATION riuscito.

Le differenze di importo o valuta e le acquisizioni non riuscite vanno sempre su Adyen payment on hold.

Debug log: scrive le chiamate API e gli eventi webhook in logs/adyg_debug.log.php nella cartella del modulo. Il file non può essere aperto dal web. Gli errori vengono sempre registrati, anche quando l'interruttore è disattivato. I log non contengono mai chiavi API o HMAC né dati personali degli acquirenti. Predefinito: disattivato.

Log: mostra la dimensione e le voci più recenti del log. Fai clic su Clear log per svuotarlo.

Delete data on uninstall: se attivo, la disinstallazione del modulo rimuove le impostazioni del modulo, i record dei pagamenti Adyen (riferimenti PSP, eventi webhook, rimborsi) e i log. Lo stato dell'ordine Adyen payment on hold e gli ordini restano. Predefinito: disattivato.

Checkout

Nella fase di pagamento il cliente sceglie il metodo di pagamento (per impostazione predefinita Adyen) e vede la nota You will be redirected to Adyen to complete the payment securely. Dopo la conferma, il modulo crea un link di pagamento Adyen per il totale del carrello nella valuta del carrello e invia il cliente alla pagina di pagamento di Adyen. Lì il cliente paga con uno qualsiasi dei metodi attivi nel tuo account Adyen. L'e-mail, il nome e il paese di fatturazione del cliente e la lingua del negozio vengono passati ad Adyen, e il pagamento compare come Cart # con il numero del carrello. In questa fase non esiste ancora alcun ordine.

Dopo il pagamento il cliente torna al tuo negozio. Il ritorno non crea né paga alcun ordine: l'ordine viene segnato come pagato solo quando Adyen lo conferma con il webhook AUTHORISATION firmato e l'importo e la valuta corrispondono al carrello. Se il webhook è già arrivato, il cliente vede la normale pagina di conferma dell'ordine con Your payment with Adyen has been received. (o Your payment with Adyen has been received and is being reviewed by the store. per un ordine in sospeso). Se Adyen ha annullato il pagamento prima, la pagina mostra Your Adyen payment was not completed. Please contact us about this order. Se il webhook non è ancora arrivato, una pagina Payment confirmation mostra Your payment is being confirmed by Adyen. Your order will be created as soon as Adyen confirms the payment, and you will receive an e-mail. con i pulsanti Check again e Back to checkout, per un cliente che non ha completato il pagamento.

Se il pagamento viene rifiutato, non viene creato alcun ordine e il cliente può riprovare. Quando il cliente avvia un nuovo pagamento per lo stesso carrello, il link di pagamento precedente scade, quindi non può più essere pagato. Se il carrello ha già un ordine, il cliente va alla conferma di quell'ordine invece che a un nuovo pagamento.

Se il link di pagamento non può essere creato, il cliente resta al checkout con Payment could not be initiated. Please try again or choose another payment method. Il motivo viene scritto nel log. Se le impostazioni sono incomplete, il messaggio è Payment gateway is not configured properly. Please contact the store administrator.

Gli sviluppatori possono modificare la richiesta del link di pagamento con l'hook actionAdygPaymentLinkRequest.

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

Ordini e rimborsi

Stati dell'ordine

No order yet: il cliente è stato inviato ad Adyen e non ha pagato, il pagamento è stato rifiutato o Adyen non ha ancora confermato il pagamento. Esiste solo il carrello.

Payment accepted, Delivered or Adyen payment on hold: il pagamento è stato autorizzato. Lo stato segue Order status after payment. Il pagamento viene registrato con il riferimento PSP di Adyen come ID transazione, e una nota mostra l'importo, il riferimento PSP e il metodo di pagamento.

Adyen payment on hold after payment: Adyen ha confermato un importo o una valuta diversi dal totale del carrello (per esempio, il carrello è stato modificato dopo l'avvio del pagamento), un'acquisizione non è riuscita o il pagamento è arrivato dopo l'annullamento dell'ordine. La nota lo spiega. Controlla il pagamento nell'area clienti, poi evadi l'ordine o rimborsa il pagamento.

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

Refunded: il pagamento è stato rimborsato integralmente tramite il modulo.

Se arriva un secondo pagamento riuscito per un ordine già pagato, per esempio da un vecchio link di pagamento, l'ordine non cambia. Una nota ti chiede di verificare nell'area clienti un eventuale addebito duplicato e di rimborsarlo lì, se necessario.

Blocco pagamento Adyen

La pagina dell'ordine mostra un blocco Adyen payment con il riferimento PSP, il link di pagamento, l'account commerciante e l'ambiente, lo stato del pagamento, l'importo pagato e rimborsato, un badge Test mode per i pagamenti di test, lo storico dei rimborsi e le Adyen notes: le note che il modulo aggiunge all'ordine (pagamento autorizzato, differenza di importo, pagamento duplicato, acquisizione, annullamento, esiti dei rimborsi), dalla più recente. Queste note sono messaggi privati dell'ordine; PrestaShop 8.2 e 9 non le mostrano altrove nella pagina dell'ordine.

Rimborsi

Nel blocco Adyen payment inserisci l'importo (viene compilato l'importo non ancora rimborsato), facoltativamente un motivo, e fai clic su Refund via Adyen. Conferma la domanda Refund this amount through Adyen? This cannot be undone. Sono supportati rimborsi totali e parziali. Ti serve il permesso di modificare gli ordini. I rimborsi vengono effettuati nell'importo e nella valuta autorizzati da Adyen, quindi dopo una differenza di importo o di valuta puoi rimborsare fino a quanto il cliente ha effettivamente pagato, non il totale dell'ordine. Il rimborso viene inviato all'ambiente e all'account commerciante con cui è stato effettuato il pagamento, quindi la chiave API di quell'ambiente deve essere impostata. Se Adyen non accetta la richiesta, il blocco mostra l'errore e non viene registrato alcun rimborso.

Adyen elabora i rimborsi in modo asincrono: la richiesta viene aggiunta allo storico dei rimborsi e alle note con lo stato received, e l'esito finale arriva tramite il webhook REFUND o REFUND_FAILED. Un rimborso non riuscito non viene più considerato rimborsato. Quando i rimborsi inviati raggiungono l'importo pagato, l'ordine passa a Refunded. Un rimborso parziale non cambia lo stato. Con l'acquisizione manuale in Adyen, si possono rimborsare solo i pagamenti acquisiti.

Il modulo non crea note di credito. I pulsanti di rimborso standard di PrestaShop nella pagina dell'ordine non restituiscono denaro tramite Adyen. I rimborsi effettuati nell'area clienti di Adyen arrivano tramite webhook e vengono aggiunti alle note. Lo stato dell'ordine e le note di credito non vengono modificati automaticamente.

Chiave di licenza

Il modulo funziona con una chiave di licenza VibeFox da vibefox.net. Il blocco licenza License — VibeFox Adyen Gateway è il primo blocco di Modules > Module Manager > VibeFox Adyen Gateway > Configure, sopra le impostazioni. Inserisci la chiave in License key e fai clic su Activate. Dopodiché il blocco mostra la chiave mascherata, lo stato (per esempio la data fino alla quale la licenza è attiva e il tuo dominio) e i pulsanti Check now per controllare di nuovo lo stato, Change key per inserire un'altra chiave e Remove key per rimuovere la chiave da questo negozio. Sotto di essi si trovano la riga Product: presta-payment-adyen e il link Manage licenses and domains in your account, che apre il tuo account vibefox.net. Solo i dipendenti con il permesso Configure per il modulo possono modificare la chiave. I testi del blocco seguono la lingua del back office (sono inclusi inglese e russo).

Se la chiave non viene accettata, il blocco indica il motivo, per esempio Key not found, This key belongs to another product, Domain limit reached oppure License expired on seguito da una data. Dopo aver cambiato l'indirizzo del negozio, o dopo aver liberato un posto dominio nel tuo account, fai clic su Check now. Se il server delle licenze non è raggiungibile, il modulo continua a funzionare con l'ultimo stato noto.

Una chiave funziona su un solo dominio: quello del negozio principale, anche in una configurazione multistore. Rimuovere la chiave dal negozio non libera il suo posto dominio. Libera il posto nel tuo account vibefox.net.

Senza una chiave attiva, 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. La vetrina di PrestaShop non sa che sei connesso al back office, quindi il metodo di pagamento viene nascosto anche a te: puoi configurare il modulo prima di acquistare una chiave, ma non testarlo nel checkout. Un promemoria compare in Modules > Module Manager, nella scheda Alerts. Gli ordini esistenti non sono interessati: i pagamenti già avviati vengono comunque confermati e i rimborsi funzionano.

Quando una licenza scade, il modulo continua a funzionare, ma aggiornamenti e supporto richiedono un rinnovo. Lo stato viene ricontrollato automaticamente mentre lavori nel back office: una volta al giorno per i primi 14 giorni dopo l'inserimento della chiave, poi una volta alla settimana. Non serve alcun cron job. La disinstallazione o il ripristino del modulo rimuovono sempre la chiave di licenza e lo stato della licenza.

Risoluzione dei problemi

Adyen non compare 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. In Payment > Preferences verifica che il modulo sia consentito per la valuta del carrello, il paese del cliente e il gruppo del cliente.

Il pagamento è andato a buon fine, ma non è stato creato alcun ordine: il webhook non funziona. Nell'area clienti dell'ambiente che usi (test o live) verifica che il webhook Standard esista, che il suo URL sia esattamente quello mostrato in Webhook URL e che il metodo sia JSON. Verifica che la chiave HMAC di quel webhook sia nel campo giusto (Test HMAC key o Live HMAC key). Con una chiave HMAC non valida o mancante il modulo risponde HTTP 401 e Adyen riprova la consegna più tardi, quindi l'ordine viene creato automaticamente appena la chiave è corretta. Il log mostra Webhook rejected: invalid HMAC signature oppure che la chiave HMAC non è configurata.

Il webhook risponde [rejected] HMAC key not configured: la chiave HMAC dell'ambiente della notifica è vuota. Incollala nelle impostazioni.

Il webhook risponde [rejected] busy, retry later: il carrello era in elaborazione da un'altra consegna nello stesso momento, oppure non è stato possibile creare l'ordine (per esempio perché il modulo è disattivato). Adyen riprova automaticamente il webhook. Il motivo è nel log.

L'URL del webhook mostra [rejected] POST required in the browser: è normale. L'URL accetta solo notifiche da Adyen.

L'avviso sulla chiave HMAC al salvataggio: il campo deve contenere la chiave HMAC esadecimale dell'area clienti. È stato mantenuto il valore precedente.

Il cliente vede Payment could not be initiated: controlla il campo Log nella pagina del modulo (gli errori vengono sempre registrati). Verifica la chiave API, l'account commerciante e, in modalità live, il prefisso URL live.

L'ordine è Adyen payment on hold dopo il pagamento: leggi la nota sull'ordine. L'importo o la valuta confermati da Adyen non corrispondevano al carrello, un'acquisizione non è riuscita o il pagamento è arrivato dopo un annullamento. Può dipendere anche dall'impostazione Order status after payment.

Il rimborso non riesce: l'ordine deve avere un riferimento PSP Adyen, che arriva con il webhook AUTHORISATION. Le credenziali dell'ambiente in cui è stato effettuato il pagamento devono essere impostate; altrimenti il blocco indica che le credenziali non sono configurate. Con l'acquisizione manuale, si possono rimborsare solo i pagamenti acquisiti.

Disinstallazione

Vai in Modules > Module Manager, apri il menu accanto a VibeFox Adyen Gateway e scegli Uninstall. La chiave di licenza e lo stato della licenza di questo modulo vengono sempre rimossi. Se Delete data on uninstall è attivo, vengono rimosse le impostazioni del modulo, i record dei pagamenti Adyen (riferimenti PSP, eventi webhook, rimborsi) e i log. Se è disattivo, tutti questi dati vengono conservati per una successiva reinstallazione, così gli ordini pagati prima possono ancora essere rimborsati. Lo stato dell'ordine Adyen payment on hold resta sempre. Gli ordini esistenti mantengono le loro note di pagamento e gli ID transazione.

Adyen è un marchio di proprietà del suo titolare. Questo modulo non è affiliato né approvato da Adyen.