Il modulo PayPlug per Magento 2 si installa con Composer, da riga di comando. È quindi necessario l'accesso SSH al server.
In sintesi: installa il modulo, collega il tuo account, attiva i metodi di pagamento, verifica i cron.
Sommario:
1. Requisiti
3. Collegare l'account PayPlug
4. Attivare i metodi di pagamento
5. Verificare che l'installazione funzioni
10. Smettere di usare il modulo
1. Requisiti
-
Versione di Magento: Adobe Commerce o Magento Open Source dalla 2.4.4 alla 2.4.9. Le versioni dalla 2.4.0 alla 2.4.3 girano su PHP 7.4 e non possono installare il modulo.
-
PHP: dalla 8.1 alla 8.5, con le estensioni
openssleintl.
-
Accesso al server: Composer e accesso da riga di comando alla root di Magento.
-
Pannello di amministrazione: l'installazione dal pannello di amministrazione non è più possibile, poiché Magento ha rimosso l'Extension Manager nella 2.4.0.
2. Installare il modulo
Esegui questi comandi dalla root di Magento:
composer require payplug/payplug-magento2 php bin/magento module:enable Payplug_Payments --clear-static-content php bin/magento setup:upgrade php bin/magento setup:di:compile php bin/magento setup:static-content:deploy fr_FR en_US php bin/magento cache:clean
composer require potrebbe richiedere le tue chiavi Adobe Commerce: nome utente = Public Key, password = Private Key.
Importante: al di fuori della modalità production, aggiungi
--forceal comandosetup:static-content:deploy, altrimenti fallisce.
3. Collegare l'account PayPlug
Oauth2, la modalità di connessione consigliata
Nulla da reinserire e nessuna password memorizzata nella configurazione di Magento.
- Vai in Stores > Configuration > Sales > Payplug Payments.
- Nel blocco Oauth2 Authentication, clicca su Connect to Payplug e autorizza la connessione.
- Nel blocco General configuration, imposta Mode su Test o Live.
- Scegli la Payment Page: Embedded, Redirected o Pop-up.
- Salva la configurazione.
L'autenticazione standard resta disponibile
La connessione tramite e-mail e password è ancora attiva, nel blocco Standard Auth, subito sotto. È attiva una sola modalità alla volta: finché Oauth2 è connesso, i campi e-mail e password restano nascosti. Disconnetti Oauth2 per tornare a usarli.
Quale pagina di pagamento scegliere?
La pagina Embedded richiede un checkout conforme agli standard Magento. Se il pulsante d'ordine è stato personalizzato, scegli Redirected.
4. Attivare i metodi di pagamento
Collega l'account prima di questo passaggio: è la connessione che recupera i metodi per cui il tuo account è idoneo, con i relativi paesi e importi.
Ogni metodo ha il proprio blocco in Stores > Configuration > Sales > Payment Methods, chiamato "Payplug Payments - <metodo>": Standard per la carta, pagamento rateale, richiesta di pagamento, Oney, Apple Pay, American Express, Bancontact, iDEAL, MyBank, Bizum, Wero, Satispay, Scalapay.
Per ogni metodo:
- Imposta Enabled su Yes.
- Configura il titolo mostrato al checkout, gli stati dell'ordine, i paesi, gli importi minimo e massimo e l'ordine di visualizzazione.
- Salva, poi svuota la cache.
Il semplice salvataggio della configurazione risincronizza l'idoneità, i paesi e gli importi dalla nostra API. È la prima cosa da provare quando un metodo non compare al checkout.
Importante: il blocco Hosted Fields Advanced richiede credenziali che forniamo caso per caso. Non attivarlo senza di esse.
5. Verificare che l'installazione funzioni
Resta in Test Mode ed effettua un ordine completo, usando le carte di test della nostra documentazione. Tre controlli:
- Il metodo di pagamento compare correttamente alla fine del carrello.
- Dopo il pagamento, l'ordine esce da Pending Payment e passa allo stato configurato nel suo blocco.
- La transazione compare nel tuo portale PayPlug, in modalità test.
Nel pannello di amministrazione, l'ordine assume quindi lo stato configurato e il blocco Payment Information mostra l'identificativo Payplug, la data del pagamento, la carta utilizzata e la modalità.
Se il pagamento va a buon fine lato PayPlug ma l'ordine resta in Pending Payment, passa alla sezione successiva: sono i cron.
6. Verificare i cron
Il modulo ha bisogno di due gruppi di cron. Senza di essi, l'installazione sembra funzionare, poi gli ordini si bloccano al primo pagamento confermato in ritardo.
| Gruppo di cron | Ruolo |
|---|---|
| payplug | Recupera i pagamenti confermati in ritardo, cattura i pagamenti differiti al termine del periodo. |
| default | Elabora le code di messaggi che creano fatture e note di credito. |
Il comando bin/magento cron:install copre entrambi. Il dettaglio dei job e dei consumer si trova nella documentazione Asynchronous Processing (order statuses, invoices & refunds).
7. Negozio con tema Hyvä
Il modulo principale resta indispensabile, perché gestisce i pagamenti, le notifiche e gli ordini. Ad esso si aggiungono due moduli per la visualizzazione:
composer require payplug/payplug-magento-hyva-checkout composer require payplug/payplug-magento-hyva-theme
Questi moduli richiedono una versione esatta del modulo principale, non un intervallo di versioni. Non potrai quindi aggiornarlo da solo, Composer lo rifiuterà, e una versione appena rilasciata del modulo principale potrebbe non avere ancora un corrispettivo Hyvä.
Importante: prima di qualsiasi aggiornamento, apri il
composer.jsondel modulo Hyvä e verifica la versione richiesta nel suorequire.
8. Aggiornare il modulo
composer require --update-with-all-dependencies payplug/payplug-magento2:^4.8 php bin/magento setup:upgrade php bin/magento setup:di:compile php bin/magento setup:static-content:deploy fr_FR en_US php bin/magento cache:clean
Leggi i blocchi ACTION REQUIRED del changelog del modulo per tutte le versioni attraversate, non solo per l'ultima. Alcune richiedono un intervento manuale.
9. Monitoraggio degli ordini
Un ordine PayPlug nasce in Pending Payment e vi resta fino al primo aggiornamento di stato valido, qualunque sia il metodo utilizzato. Tre meccanismi lo fanno avanzare: il ritorno del cliente dalla pagina di pagamento, la notifica inviata dai nostri server a ogni cambio di stato e il cron di riconciliazione che recupera le conferme tardive.
Due pulsanti completano il dispositivo in alto nella scheda dell'ordine, finché il pagamento non è risolto:
- Update Payment: interroga la nostra API su richiesta.
-
Send new payment link: sollecita un cliente il cui pagamento non è andato a buon fine.
Una volta che l'ordine passa in Processing, questi pulsanti scompaiono: non c'è più nulla da riconciliare.
Finché l'ordine è in Pending Payment, puoi annullarlo dall'elenco degli ordini, singolarmente o in blocco.
10. Smettere di usare il modulo
Non disinstallarlo: Magento ha bisogno del suo codice per visualizzare gli ordini già pagati con PayPlug, e genera un errore se non lo trova più.
Imposta Enabled su No in ogni blocco "Payplug Payments - <metodo>". PayPlug scompare dal checkout e gli ordini esistenti restano leggibili.
11. Problemi frequenti
| Sintomo | Causa probabile | Cosa fare |
|---|---|---|
| Class Payplug\Authentication does not exist | La libreria PHP PayPlug non è installata |
composer require payplug/payplug-php:^4.2 poi composer require giggsey/libphonenumber-for-php:"^8.10|^9.0"
|
| Composer rifiuta di aggiornare il modulo principale | Versione bloccata da un modulo Hyvä | Aggiornare entrambi insieme (sezione 7) |
| Un metodo di pagamento non compare al checkout | Idoneità non sincronizzata, paese o importo fuori dai limiti | Salvare la configurazione, poi verificare paesi e importi del blocco |
| Ordine bloccato in Pending Payment mentre il pagamento risulta confermato nel portale | Il gruppo di cron payplug non è in esecuzione | Verificare il cron (sezione 6) |
| Pagamento confermato senza fattura, rimborso assente | Il gruppo di cron default non è in esecuzione, o i consumer sono esclusi | Verificare il cron e app/etc/env.php
|
| La pagina di pagamento Embedded non si visualizza | Checkout personalizzato | Passare a Redirected |
I log del modulo si trovano in var/log/payplug_payments.log. Allegali alla tua richiesta se ci contatti.