--- title: "PrestaShop" description: "Modulo Fabrick Checkout per PrestaShop 8 e 9: installazione, configurazione di credenziali e API Key, stati ordine, Pay By Link, salvataggio carta, riconciliazione CRON dei pagamenti in attesa, rimborsi, test e risoluzione problemi." url: "https://docs.fabrick.com/payment-hub-and-orchestra/ecommerce/integration-methods/plugin/prestashop/" language: "it" --- # PrestaShop ### ✓ — REST API ✓ — Web Component ✓ — 3DS2 – Autenticazione ✓ — Pay By Link ✓ — Tokenizzazione (salvataggio carta) ✓ — Riconciliazione pagamenti in attesa (CRON) ✓ — Rimborsi dal backoffice ✓ — Multinegozio Il modulo **Fabrick Checkout** integra i pagamenti di **Fabrick Payment Orchestra** in PrestaShop tramite le **REST API** e il [Web Component](https://docs.fabrick.com/payment-hub-and-orchestra/ecommerce/integration-methods/web-component/) ``. 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. > **Metodi di pagamento** > > Il modulo utilizza il Web Component ``, 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](https://docs.fabrick.com/payment-hub-and-orchestra/ecommerce/integration-methods/plugin/prestashop/#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](https://docs.fabrick.com/payment-hub-and-orchestra/ecommerce/alternative-payments/apple-pay/#configurazione-aggiuntiva-per-web-component-e-lightbox) e [Google Pay](https://docs.fabrick.com/payment-hub-and-orchestra/ecommerce/alternative-payments/google-pay/#configurazione-aggiuntiva-per-web-component-e-webview) > **Moduli di checkout di terze parti** > > La compatibilità non è garantita se sono installati moduli che modificano il normale flusso del checkout di PrestaShop. --- ## Installazione 1. Carica l'archivio del modulo, oppure copia la cartella `fabrickcheckout` nella directory `modules/` del negozio. 2. Nel backoffice PrestaShop vai in **Moduli**, cerca **Fabrick Checkout** e clicca su **Installa**. 3. Clicca su **Configura** e compila le impostazioni descritte nella sezione [Configurazione del modulo](https://docs.fabrick.com/payment-hub-and-orchestra/ecommerce/integration-methods/plugin/prestashop/#configurazione-del-modulo). 4. Verifica che il modulo sia **attivo** e disponibile per le valute del carrello. > **Aggiornamento del modulo** > > 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 1. Vai in **Configurazione > Sicurezza > APIKEY** e apri la gestione delle chiavi. ![Sezione APIKEY del back-office Fabrick](https://docs.fabrick.com/assets/images/fabrickcheckout-bo-apikey-53a4bdcba101b860b315335ce12e5eda.png) 2. Clicca su **Aggiungi Chiave**. ![Creazione di una nuova API Key](https://docs.fabrick.com/assets/images/fabrickcheckout-bo-apikey-aggiungi-ea5d427b1ef54cf276267c92a2c216b0.png) 3. Usa l'icona di **copia** accanto alla chiave creata e incollala nel campo **API Key** del modulo PrestaShop. > **API Key** > > 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**: - `PaymentMethod` - `Token` - `Token ExpiryMonth` - `Token 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. ![Elenco dei parametri in Campi \& Parametri](https://docs.fabrick.com/assets/images/fabrickcheckout-bo-parametri-0a4fd36eefbb503b96698f9474e4d622.png) ![Parametro PaymentMethod con Risposta e Risposta Web Service](https://docs.fabrick.com/assets/images/fabrickcheckout-bo-paymentmethod-ae606fb6cf80136595d869ea62ed7ae4.png) --- ## Configurazione del modulo La configurazione si trova in **Moduli > Fabrick Checkout > Configura**. > **Multinegozio** > > 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*. ![Configurazione del modulo Fabrick Checkout](https://docs.fabrick.com/assets/images/fabrickcheckout-configurazione-1-4327ecb342b4be78952de5e06d3b46f4.png) ![Opzioni funzionali del modulo Fabrick Checkout](https://docs.fabrick.com/assets/images/fabrickcheckout-configurazione-2-eb8a9a6b05636da2a5c44b365cee3e29.png) ### 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](https://docs.fabrick.com/payment-hub-and-orchestra/ecommerce/integration-methods/plugin/prestashop/#creazione-e-copia-dellapi-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](https://docs.fabrick.com/payment-hub-and-orchestra/ecommerce/integration-methods/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](https://docs.fabrick.com/payment-hub-and-orchestra/ecommerce/integration-methods/plugin/prestashop/#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**. > **Stato dedicato a Pay By Bank** > > 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](https://docs.fabrick.com/payment-hub-and-orchestra/ecommerce/integration-methods/plugin/prestashop/#riconciliazione-dei-pagamenti-in-attesa-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. ![Riconciliazione dei pagamenti in attesa](https://docs.fabrick.com/assets/images/fabrickcheckout-cron-6878e96ac22c552debb9b5ff5c33f0e6.png) | 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: ```text 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. ![Rimborso manuale dal backoffice PrestaShop](https://docs.fabrick.com/assets/images/fabrickcheckout-rimborso-6d5dbaea623b0a6b4561696e09ab6af5.png) 1. Inserisci il **Payment ID** del pagamento, oppure il **Bank Transaction ID** o lo **Shop Transaction ID** se li conosci. 2. Indica l'**Importo** e la **Valuta (ISO)**, entrambi obbligatori, ed eventualmente il **Motivo**. 3. Clicca su **Esegui rimborso**. > **Limiti del rimborso manuale** > > - 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 1. Il cliente completa il carrello e il checkout fino alla scelta del pagamento. 2. Seleziona **Pay with Fabrick** e, se previsto, la casella per il salvataggio della carta. 3. Viene reindirizzato alla pagina dedicata e completa il pagamento nel Web Component, con carta o con uno degli APM disponibili. 4. 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](https://docs.fabrick.com/payment-hub-and-orchestra/ecommerce/features/token/). ### 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 1. Attiva **Modalità sandbox** e inserisci le credenziali di test. 2. Esegui i pagamenti con le [carte di test](https://docs.fabrick.com/payment-hub-and-orchestra/ecommerce/testing/sandbox-cards/) Fabrick, ad esempio per i flussi frictionless, challenge e autenticazione 3DS fallita. 3. Verifica la creazione dell'ordine, gli stati e, se utilizzato, il salvataggio della carta. 4. Con **Log di debug** attivo, controlla i file `var/logs/fabrickcheckout-{id_shop}-AAAA-MM-GG` sul server. 5. Verifica che un pagamento rifiutato riporti il cliente allo step di pagamento con l'avviso in testata. > **Carte reali** > > 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](https://docs.fabrick.com/payment-hub-and-orchestra/ecommerce/integration-methods/plugin/prestashop/#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](https://landing.fabrick.com/fabrick-dashboard-support).