PrestaShop
Il modulo Fabrick Checkout integra i pagamenti di Fabrick Payment Orchestra in PrestaShop tramite le REST API e il Web Component <fbk-checkout>. Il buyer completa il pagamento su una pagina dedicata del negozio, dove il Web Component presenta la carta e i metodi di pagamento alternativi (APM) abilitati sullo shopLogin.
Il modulo utilizza il Web Component <fbk-checkout>, che presenta tutti i metodi di pagamento abilitati sullo shopLogin: non è quindi previsto un elenco di metodi supportati dal plugin. Per attivare un metodo è sufficiente abilitarlo sullo shopLogin; Apple Pay e Google Pay richiedono anche la configurazione indicata nei Requisiti.
Funzionalità principali
- Pagamento standard con carta e APM abilitati sullo shopLogin
- Checkout su pagina dedicata (Redirect) con il Web Component Fabrick
- Pay By Link (opzionale)
- Salvataggio carta con consenso del cliente e gestione dall'area Account (opzionale)
- Notifiche server-to-server e ritorno del buyer al negozio
- Riconciliazione dei pagamenti in attesa tramite CRON, ad esempio per Pay By Bank
- Rimborsi dal backoffice PrestaShop
- Multinegozio (multishop), con configurazione e credenziali per singolo negozio
Requisiti
- PrestaShop 8.0 o successivo, oppure 9.x
- Account Fabrick con Payment Orchestra, Web Components e REST API abilitati
- Credenziali Shop Login e API Key, di sandbox o di produzione
- HTTPS sul dominio del negozio: consigliato in sandbox, obbligatorio in produzione
- Per Apple Pay e Google Pay, la configurazione dei wallet per il Web Component, descritta nelle pagine Apple Pay e Google Pay
La compatibilità non è garantita se sono installati moduli che modificano il normale flusso del checkout di PrestaShop.
Installazione
- Carica l'archivio del modulo, oppure copia la cartella
fabrickcheckoutnella directorymodules/del negozio. - Nel backoffice PrestaShop vai in Moduli, cerca Fabrick Checkout e clicca su Installa.
- Clicca su Configura e compila le impostazioni descritte nella sezione Configurazione del modulo.
- Verifica che il modulo sia attivo e disponibile per le valute del carrello.
Dopo un aggiornamento eseguito senza reinstallare il modulo, apri almeno una volta la pagina di configurazione: il modulo verifica e ripristina automaticamente la registrazione degli hook e la configurazione.
Configurazione del back-office Fabrick
Prima di configurare il modulo è necessario recuperare le credenziali e abilitare alcuni parametri di risposta nel back-office merchant Fabrick.
Creazione e copia dell'API Key
- Vai in Configurazione > Sicurezza > APIKEY e apri la gestione delle chiavi.
- Clicca su Aggiungi Chiave.
- Usa l'icona di copia accanto alla chiave creata e incollala nel campo API Key del modulo PrestaShop.
L'API Key consente di eseguire operazioni sui pagamenti dello shopLogin: non condividerla e non esporla al di fuori della configurazione del modulo. Le credenziali di sandbox e di produzione sono diverse.
Parametri in risposta
In Pagina di Pagamento > Campi & Parametri abilita in risposta i seguenti parametri, su entrambe le pagine:
PaymentMethodTokenToken ExpiryMonthToken ExpiryYear
Per ciascun parametro apri la scheda, seleziona le voci Risposta e Risposta Web Service e clicca su Salva. Di seguito l'esempio con PaymentMethod, gli altri parametri seguono la stessa logica.
Configurazione del modulo
La configurazione si trova in Moduli > Fabrick Checkout > Configura.
Se PrestaShop gestisce più negozi, seleziona il negozio desiderato nell'intestazione del backoffice prima di aprire o salvare la configurazione. Le impostazioni valgono per il singolo negozio e non vengono applicate in blocco a Tutti i negozi.
Credenziali e ambiente
| Impostazione | Descrizione |
|---|---|
| Shop Login | Codice merchant assegnato da Fabrick |
| API Key | Chiave API creata nel back-office Fabrick (vedi Creazione e copia dell'API Key) |
| Modalità sandbox | Sì: le richieste sono inviate all'ambiente di test. No: le richieste sono inviate all'ambiente di produzione |
| Log di debug | Scrive log giornalieri in var/logs/fabrickcheckout-{id_shop}-AAAA-MM-GG. Da attivare solo per diagnosi temporanee e da disattivare in produzione: i file più vecchi di 14 giorni vengono eliminati automaticamente |
Opzioni funzionali
| Impostazione | Descrizione |
|---|---|
| Abilita funzionalità Pay by Link | Mostra al checkout l'opzione di pagamento tramite Pay By Link |
| Validità Pay by Link (ore) | Durata di validità del link di pagamento, fino a un massimo di 49 ore |
| Consenti ai clienti di salvare la carta | Mostra al checkout la casella Salva la mia carta per i pagamenti futuri e la pagina Carte salvate nell'area Account. Vedi Carte salvate |
Stati ordine
Il modulo crea all'installazione degli stati ordine dedicati, che è possibile associare a stati PrestaShop già esistenti.
| Impostazione | Quando viene applicato | Valore predefinito |
|---|---|---|
| Stato ordine pagato / confermato | Pagamento approvato (APPROVED) | Pagamento accettato |
| Stato ordine in attesa | Ordine creato alla conferma del cliente, con pagamento ancora in attesa di esito (metodi con conferma differita) | Pending payment confirmation (Fabrick) |
| Stato ordine Pay by Bank in attesa | Ordine pagato con Pay By Bank in attesa dell'esito del bonifico | Awaiting Pay by Bank transfer (Fabrick) |
Sono configurabili anche gli stati per Pay By Link in attesa / pagato e per pagamento fallito.
Uno stato dedicato agli ordini Pay By Bank facilita il tracciamento dei bonifici che non ricevono un esito immediato: questi ordini restano in attesa fino alla riconciliazione, automatica tramite CRON o manuale.
Riconciliazione dei pagamenti in attesa (CRON)
Alcuni metodi, come Pay By Bank e Pay By Link, restituiscono l'esito finale in un momento successivo al ritorno del buyer sul negozio. Il CRON di riconciliazione ricontrolla periodicamente su Fabrick gli ordini che si trovano negli stati di attesa dedicati e li aggiorna solo quando è disponibile un esito finale, positivo o negativo.
Le sessioni di checkout abbandonate e gli altri metodi di pagamento sono esclusi dalla riconciliazione.
| Impostazione | Descrizione |
|---|---|
| Abilita CRON di riconciliazione | Attiva la riconciliazione per il negozio. Se disattivata, la chiamata al CRON salta il negozio, a meno che non venga eseguita manualmente con il parametro &manual=1 |
| Giorni di ricontrollo dei pagamenti pending | Numero di giorni, dalla creazione della transazione, entro cui un ordine in attesa viene ricontrollato. Gli ordini più vecchi restano in attesa e vanno gestiti manualmente. Predefinito: 3 |
Pianificazione del CRON
Pianifica sul server una sola chiamata periodica, ad esempio ogni ora, all'URL mostrato nella pagina di configurazione:
https://tuodominio/module/fabrickcheckout/cron?fbk_key=...
- In multinegozio non serve un CRON per ogni negozio: lo stesso URL, sul dominio principale e senza il percorso del singolo negozio (ad esempio
/shop2/), riconcilia tutti i negozi con il CRON abilitato. - Il valore di
fbk_keyè la chiave del negozio predefinito, generata all'installazione: non va condivisa pubblicamente. - Il CRON non imposta mai un ordine come fallito di propria iniziativa: applica esclusivamente l'esito restituito da Fabrick.
Rimborso manuale
Dalla sezione Rimborso manuale della configurazione è possibile rimborsare un pagamento già eseguito con Fabrick.
- Inserisci il Payment ID del pagamento, oppure il Bank Transaction ID o lo Shop Transaction ID se li conosci.
- Indica l'Importo e la Valuta (ISO), entrambi obbligatori, ed eventualmente il Motivo.
- Clicca su Esegui rimborso.
- Non è possibile rimborsare più di quanto resta disponibile: il modulo controlla l'importo pagato e sottrae gli eventuali rimborsi già eseguiti sullo stesso pagamento.
- Lo stato dell'ordine in PrestaShop non viene aggiornato automaticamente: se necessario, aggiornalo manualmente dalla scheda dell'ordine.
Esperienza di pagamento
Il modulo utilizza la modalità Redirect: il pagamento avviene su una pagina dedicata del modulo, che integra il Web Component Fabrick.
Pagamento standard
- Il cliente completa il carrello e il checkout fino alla scelta del pagamento.
- Seleziona Pay with Fabrick e, se previsto, la casella per il salvataggio della carta.
- Viene reindirizzato alla pagina dedicata e completa il pagamento nel Web Component, con carta o con uno degli APM disponibili.
- Al termine l'ordine viene confermato in PrestaShop, oppure resta nello stato di attesa previsto per il metodo utilizzato.
Se il pagamento viene rifiutato, ad esempio per autenticazione 3DS fallita, il cliente torna allo step di pagamento del checkout e visualizza in testata un avviso di pagamento non completato, con il motivo restituito da Fabrick quando disponibile.
Pay By Link
Se l'opzione è abilitata, al checkout compare una scelta dedicata al pagamento tramite link. Il cliente riceve o utilizza il link secondo la configurazione Fabrick e l'ordine può restare nello stato di attesa fino all'esito del pagamento.
Carte salvate
Con l'opzione Consenti ai clienti di salvare la carta attiva:
- la casella Salva la mia carta per i pagamenti futuri è mostrata solo ai clienti registrati e autenticati, non agli ospiti;
- la carta viene tokenizzata solo se il cliente seleziona la casella prima di completare il pagamento;
- ai pagamenti successivi può comparire l'opzione Pay with saved card, con circuito, ultime cifre e scadenza della carta;
- dall'area Account > Carte salvate il cliente visualizza le carte salvate e può eliminarle; l'eliminazione revoca il token anche su Fabrick, quando possibile.
Con l'opzione disattiva non viene richiesto alcun token e restano disponibili tutti i metodi di pagamento. Per il funzionamento della tokenizzazione consulta la sezione Tokenizzazione.
Ritorno del buyer e notifiche
- Ritorno del buyer: al termine del pagamento il cliente viene riportato sul negozio.
- Notifica server-to-server: aggiorna lo stato dell'ordine lato server in modo affidabile, anche se il cliente non torna sul negozio. Non disabilitare gli URL pubblici del modulo, che devono restare raggiungibili da Fabrick.
Sandbox e test
- Attiva Modalità sandbox e inserisci le credenziali di test.
- Esegui i pagamenti con le carte di test Fabrick, ad esempio per i flussi frictionless, challenge e autenticazione 3DS fallita.
- Verifica la creazione dell'ordine, gli stati e, se utilizzato, il salvataggio della carta.
- Con Log di debug attivo, controlla i file
var/logs/fabrickcheckout-{id_shop}-AAAA-MM-GGsul server. - Verifica che un pagamento rifiutato riporti il cliente allo step di pagamento con l'avviso in testata.
Non utilizzare carte reali nell'ambiente sandbox.
Checklist di go-live
Prima di attivare il modulo in produzione, verifica i seguenti punti:
- Modalità sandbox impostata su No
- Shop Login e API Key di produzione
- Log di debug disattivato, o attivo solo per il tempo necessario
- Sito in HTTPS e URL del modulo raggiungibili da Fabrick
- CRON pianificato, se utilizzi metodi con esito differito come Pay By Bank
- Test end-to-end completati con carta e con gli APM abilitati
- Apple Pay e Google Pay configurati per il dominio di produzione, se utilizzati
Risoluzione dei problemi
Parti dalle verifiche più semplici, configurazione e cache, e solo dopo approfondisci log e rete.
| Problema | Verifiche |
|---|---|
| Il metodo di pagamento non compare al checkout | Verifica che il modulo sia installato e attivo, che la valuta del carrello sia tra quelle abilitate e che Shop Login e API Key siano impostati correttamente. Anche eventuali restrizioni di paese o valuta sul profilo Fabrick possono nascondere il metodo |
| Pagina bianca dopo Pay with Fabrick | Svuota la cache del tema e di Smarty e riprova. Controlla nella console del browser eventuali errori di caricamento dello script fbk-elements.js e l'assenza di blocchi CSP o di rete |
| La carta non viene salvata | L'opzione di salvataggio deve essere attiva e il cliente deve aver selezionato Salva la mia carta prima di completare il pagamento. Con il log di debug attivo, la sessione pagata deve riportare requestToken=MASKEDPAN e save_card_requested=1 |
| L'ordine resta in stato di attesa | Può essere normale per i metodi con esito differito, come Pay By Bank. Verifica che le notifiche server-to-server arrivino, che il CRON sia pianificato e che gli stati ordine configurati siano quelli attesi |
| Dopo un pagamento fallito non compare alcun avviso | Svuota la cache di PrestaShop e verifica che il modulo sia aggiornato e che l'hook actionFrontControllerInitAfter sia registrato: è sufficiente aprire la pagina di configurazione del modulo per ripristinarlo |
| Il rimborso non cambia lo stato dell'ordine | È il comportamento previsto: il rimborso manuale opera solo su Fabrick. Aggiorna lo stato in Ordini, se necessario |
Dove leggere i log
Con Log di debug attivo, le chiamate API sono registrate in var/logs/ del negozio PrestaShop, in un file giornaliero fabrickcheckout-{id_shop}-AAAA-MM-GG (ad esempio fabrickcheckout-1-2026-09-04). I file vengono conservati per un massimo di 14 giorni. In produzione mantieni il debug attivo solo per il tempo necessario alla diagnosi.
Per ulteriore supporto contatta l'assistenza tecnica.