--- title: "Lightbox" description: "Presenta la pagina di pagamento Fabrick in un pop-up sovrapposto al checkout, senza redirect: caricamento dello script, apertura della Lightbox, gestione tramite callback e verifica dell'esito." url: "https://docs.fabrick.com/payment-hub-and-orchestra/ecommerce/integration-methods/lightbox/" language: "it" --- # Lightbox La modalità di integrazione **Lightbox** consente di presentare al buyer la **pagina di pagamento Fabrick** attraverso un **pop-up** sovrapposto alla pagina del carrello dell’ecommerce, evitando il reindirizzamento su una nuova pagina per presentare la pagina di pagamento. La Lightbox offre un’integrazione semplice con possibilità di personalizzazione grafica limitate, in quanto l’interfaccia, i flussi di autenticazione e i redirect verso altri metodi di pagamento (APM) vengono gestiti direttamente da Fabrick. ![lightbox](https://docs.fabrick.com/assets/images/lightbox-cda1f58961de5fe1a21620204e9e4254.png) > **Blocco pop-up** > > Se sul dispositivo o sul browser in uso è attivo il blocco pop-up, questa configurazione potrebbe impedire l'apertura di nuove pagine. Su device o browser desktop non sempre viene richiesto di accettare l'apertura di una pagina esterna, e questo potrebbe impedire il completamento del pagamento. > **Compatibilità** > > La Lightbox è ottimizzata per l'utilizzo tramite browser e non garantisce la compatibilità con canali come WebView o applicazioni native. > **Amazon Pay non supportato** > > Amazon Pay non è compatibile con l'integrazione Lightbox: anche se abilitato per lo `shopLogin`, il metodo non viene mostrato nella pagina di selezione. Per offrire Amazon Pay ai tuoi clienti utilizza le integrazioni Checkout Page, Pay By Link, Web Component o API Only. ## Inizializzazione pagamento Per inizializzare una richiesta di pagamento è necessario utilizzare, lato server, la chiamata **`payment/create`**. Questa modalità garantisce un livello di sicurezza più elevato nella generazione del payload e nella gestione della API key, evitando l’esposizione di informazioni sensibili nel front‑end. La chiamata **`payment/create`** rappresenta la base della richiesta di pagamento e può essere estesa integrando i servizi messi a disposizione da Fabrick, come ad esempio: - il servizio di [**prevenzione frodi**](https://docs.fabrick.com/payment-hub-and-orchestra/ecommerce/features/fraud-prevention/fabrick-guaranteed-payments/) - le funzionalità di [**Tokenizzazione**](https://docs.fabrick.com/payment-hub-and-orchestra/ecommerce/features/token/) - gli **oggetti dedicati** ai singoli metodi di pagamento Questa flessibilità permette al merchant di costruire una richiesta di pagamento completa, personalizzabile e in linea con le proprie esigenze operative. Nelle sezioni seguenti entreremo nel dettaglio riguardo l’utilizzo dell’integrazione e dei parametri da includere in chiamata per personalizzare la richiesta di pagamento. ### Logiche di presentazione dei metodi di pagamento Durante la creazione della richiesta, se lo `shopLogin` è abilitato per più metodi di pagamento (APM), è possibile utilizzare il campo **`paymentType`** nella chiamata **`payment/create`** per specificare quali metodi presentare al buyer nella pagina di pagamento. | `paymentType` | Comportamento della Lightbox | | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- | | Non valorizzato | Mostra la pagina di selezione con tutti i metodi abilitati per lo `shopLogin` nel backoffice Gestpay che non richiedono campi obbligatori | | Più metodi, ad esempio `["FABRICKPASS", "CREDITCARD"]` | Mostra la pagina di selezione limitata ai metodi indicati | | Solo `["CREDITCARD"]` | Mostra la pagina di selezione con la carta e i wallet abilitati, come Apple Pay, Google Pay e Click to Pay | | Un solo APM, ad esempio `["FABRICKPASS"]` | Mostra la pagina di selezione con il solo metodo indicato | A differenza di Checkout Page e Pay By Link, la Lightbox presenta sempre la pagina di selezione, anche quando nel campo `paymentType` è indicato un solo metodo. > **Metodi con campi obbligatori** > > Alcuni metodi di pagamento richiedono campi obbligatori nella chiamata **`payment/create`**. Questi metodi vengono presentati al buyer solo se la chiamata include i campi previsti; in caso contrario non compaiono nella pagina di selezione. I campi richiesti da ciascun metodo sono indicati nella relativa pagina. > **Elenco completo dei paymentType** > > I possibili valori di **`paymentType`** sono disponibili nella sezione [payment type codes](https://api.paymentorchestra.fabrick.com/#payment-type-codes). In alternativa, è possibile utilizzare l'endpoint **`GET shop/paymentMethods`** per verificare in tempo reale i metodi di pagamento abilitati per lo `shopLogin` utilizzato, filtrando la risposta per `payload.paymentMethod.paymentType`. Di seguito un esempio di richiesta per ciascun caso. **Non valorizzato** Il campo `paymentType` non è presente: la Lightbox mostra la pagina di selezione con tutti i metodi abilitati per lo `shopLogin` che non richiedono campi obbligatori. **Request** ```http POST /api/v1/payment/create Host (sandbox): sandbox.gestpay.net Host (produzione): ecomms2s.sella.it Authorization: apikey **************** Content-Type: application/json ``` ```json { "shopLogin": "GESPAY12345", "amount": "100", "currency": "EUR", "shopTransactionID": "FBK_OrderID" } ``` **Più metodi** Sono indicati più metodi di pagamento, ad esempio `CREDITCARD` e `FABRICKPASS`: la Lightbox mostra la pagina di selezione limitata ai soli metodi indicati. **Request** ```http POST /api/v1/payment/create Host (sandbox): sandbox.gestpay.net Host (produzione): ecomms2s.sella.it Authorization: apikey **************** Content-Type: application/json ``` ```json { "shopLogin": "GESPAY12345", "amount": "100", "currency": "EUR", "shopTransactionID": "FBK_OrderID", "paymentType": ["CREDITCARD", "FABRICKPASS"] } ``` **Solo carta** È indicato solo `CREDITCARD`: la Lightbox mostra la pagina di selezione con la carta e i wallet abilitati, come Apple Pay, Google Pay e Click to Pay. **Request** ```http POST /api/v1/payment/create Host (sandbox): sandbox.gestpay.net Host (produzione): ecomms2s.sella.it Authorization: apikey **************** Content-Type: application/json ``` ```json { "shopLogin": "GESPAY12345", "amount": "100", "currency": "EUR", "shopTransactionID": "FBK_OrderID", "paymentType": ["CREDITCARD"] } ``` **Un solo APM** È indicato un solo metodo di pagamento alternativo, ad esempio `FABRICKPASS`: la Lightbox mostra comunque la pagina di selezione, con il solo metodo indicato. **Request** ```http POST /api/v1/payment/create Host (sandbox): sandbox.gestpay.net Host (produzione): ecomms2s.sella.it Authorization: apikey **************** Content-Type: application/json ``` ```json { "shopLogin": "GESPAY12345", "amount": "100", "currency": "EUR", "shopTransactionID": "FBK_OrderID", "paymentType": ["FABRICKPASS"] } ``` ### Pagina di conferma dell’ordine e notifica server to server Durante la creazione della richiesta è possibile utilizzare l’oggetto **`responseURLs`** per definire dinamicamente le URL di redirect e la URL di notifica server to server, che il sistema utilizzerà al termine della transazione, sia in caso di esito positivo sia in caso di esito negativo. Quando l’oggetto **`responseURLs`** viene inserito nella chiamata, **solo per questa transazione**, il sistema non utilizzerà le URL configurate nel backoffice di Gestpay, ma applicherà quelle specificate nella richiesta. Se invece l’oggetto non è presente, verranno utilizzate le configurazioni del backoffice. È possibile specificare anche solo una parte dei parametri. Ad esempio, se viene impostata solo la URL di notifica server to server o solo una delle URL di redirect, il sistema sovrascriverà solo i valori indicati, continuando ad utilizzare le altre URL configurate nel backoffice di Gestpay. Di seguito un esempio di richiesta in cui vengono definite tutte le URL di redirect e la URL di notifica server to server. **Request** ```http POST /api/v1/payment/create Host (sandbox): sandbox.gestpay.net Host (produzione): ecomms2s.sella.it Authorization: apikey **************** Content-Type: application/json ``` ```json { "shopLogin": "GESPAY12345", "amount": "100", "currency": "EUR", "shopTransactionID": "FBK_OrderID", "responseURLs": { "buyerOK": "https://merchant-url-ok.com", "buyerKO": "https://merchant-url-ko.com", "serverNotificationURL": "https://merchant-url-s2s.com" } } ``` ## Integrazione Lightbox Una volta ottenuti **PaymentToken** e **PaymentID** in risposta alla chiamata **`payment/create`**, è possibile procedere con l’integrazione della soluzione Lightbox. ### 1. JavaScript Fabrick Il primo passaggio consiste nell'includere nella pagina la libreria JavaScript dedicata, tramite un tag ` ``` > **Caricamento libreria** > > La libreria va sempre caricata dagli URL Fabrick. Una copia salvata non riceve gli aggiornamenti e potrebbe smettere di funzionare. > **Ordine di caricamento** > > Lo script Fabrick deve essere caricato prima del tuo script che lo utilizza, oppure gestito tramite callback onload, per garantire la corretta inizializzazione della libreria. ### 2. Impostazione variabili Successivamente è necessario impostare il valore dello shopLogin, utilizzando `axerve.lightBox.shop = shopLogin` > **shopLogin** > > Il valore shopLogin è univoco per ogni esercente e viene fornito da Fabrick al momento dell’attivazione del servizio. ### 3. Presentazione pagina di pagamento Dopo aver configurato lo shopLogin, è possibile aprire la Lightbox utilizzando la funzione `axerve.lightBox.open()`. La funzione richiede in input **paymentID** e **paymentToken**, ottenuti in risposta alla chiamata **`payment/create`**, e accetta inoltre un terzo parametro opzionale che consente di specificare una **callback** per la gestione personalizzata dell’esito del pagamento. **Modalità disponibili:** - #### Redirect automatico Passando **PaymentID** e **PaymentToken** alla funzione `axerve.lightBox.open(paymentID, paymentToken)`, la Lightbox verrà aperta e, al termine del pagamento, Fabrick effettuerà automaticamente il redirect verso la URL di esito positivo/negativo configurata per la transazione. Di seguito un esempio: ```html Test Pagamento Lightbox ``` --- - #### Callback Passando **PaymentID**, **PaymentToken** e, come terzo parametro, una **callback** alla funzione `axerve.lightBox.open(paymentID,paymentToken, handleCallback)` è possibile sovrascrivere il comportamento di redirect gestito da Fabrick. In questo caso, una volta concluso il pagamento, verrà richiamata la funzione di callback, che riceverà come parametro un oggetto con le seguenti informazioni: - **error**: eventuali errori riscontrati durante il processo (campi `code` e `description`) - **paymentId**: identificativo della transazione, utile per recuperare i dettagli tramite `payment/detail` - **responseURL**: URL di redirect verso la pagina di esito positivo o negativo - **status**: stato del pagamento (OK, KO) Di seguito un esempio: ```html Test Pagamento Lightbox ``` --- #### Comportamento con metodi alternativi (APM) Per tutte e due le modalità di apertura della Lightbox, se il buyer seleziona un metodo di pagamento diverso dalla carta o wallet, il sistema aprirà una nuova pagina ed effettuerà automaticamente il redirect verso il servizio selezionato. Al termine del pagamento, la pagina si chiuderà e il buyer verrà riportato automaticamente sulla pagina precedente dove la Lightbox era stata inizializzata. --- ## Conclusione transazione e Notifica del Pagamento Una volta concluso il pagamento, il pop‑up della Lightbox si chiude automaticamente e il comportamento successivo varia in base alla modalità utilizzata: - se non è stata definita una callback, Fabrick effettua il redirect del buyer verso la URL di esito positivo o negativo configurata per la transazione. - se è stata specificata una callback, il sistema restituisce un oggetto JavaScript contenente le informazioni relative all’esito, lasciando all’esercente la gestione completa del flusso successivo. Indipendentemente dalla modalità utilizzata, il sistema invia sempre una notifica server to server (S2S) con l’esito della transazione. Esempio URL di redirect e notifica S2S: - `https://merchant-url.com?a=GESPAY12345&Status=OK&paymentID=1360119538182&paymentToken=8a901523-67a5-4aca-bbd2-c7c412934289` All’interno della URL di redirect e della notifica S2S è presente il parametro **`Status`**, che permette di identificare immediatamente lo stato del pagamento. I possibili valori sono: - **`OK`**: pagamento completato con esito positivo - **`KO`**: pagamento completato con esito negativo - **`XX`**: pagamento in stato sospeso, in attesa dell’esito finale. > **Stato sospeso (XX)** > > Lo stato **`XX`** è utilizzato solo per alcuni metodi di pagamento alternativi (APM) e viene restituito quando l’esito è asincrono. In questo scenario Fabrick reindirizza il cliente alla URL di esito positivo, ma lo stato **non è ancora definitivo**: sarà necessario attendere una successiva notifica S2S che comunicherà l’esito finale (**OK** o **KO**). > > - Se ricevi lo stato XX, non procedere con la spedizione della merce o l’erogazione del servizio. > - Attendi la notifica S2S che comunicherà l’esito finale del pagamento. Per verificare l’esito o lo stato aggiornato della transazione è possibile utilizzare l’endpoint **`GET payment/detail`**, passando come parametro il **`paymentID`** restituito dalla chiamata **`payment/create`**, ottenuto dalla URL di redirect/notifica S2S o dall'oggetto javascript. Nella risposta è presente il parametro **`transactionResult`**, che indica lo stato del pagamento. I valori possibili sono: - **`AUTHENTICATED`**: pagamento autenticato (OK) - **`APPROVED`**: pagamento approvato (OK) - **`DECLINED`**: pagamento rifiutato (KO) - **`PENDING`**: pagamento in attesa di conferma (XX) - **`WAITING`**: pagamento in corso (XX) - **`UNSUBMITTED`**: il pagamento non è ancora iniziato (XX) Esempio di chiamata per verificare lo stato della transazione tramite paymentID. **Request** ```http GET /api/v1/payment/detail/{paymentID} Host (sandbox): sandbox.gestpay.net Host (produzione): ecomms2s.sella.it Authorization: apikey **************** Content-Type: application/json ``` **Response** ```json { "error": { "code": "0", "description": "request correctly processed" }, "payload": { "transactionType": "detail", "transactionResult": "APPROVED", "transactionState": "AUT", "transactionErrorCode": "0", "transactionErrorDescription": "Transaction correctly processed", "bankTransactionID": "1825", "shopTransactionID": "FBK_OrderID", "shopTransactionID_2": "", "authorizationCode": "794183", "paymentID": "1610469726440", "currency": "EUR", "country": "ITALIA", "company": "VISA", "tdLevel": "FULL", "threeDS": { "authenticationResult": { "authenticationLevel": "2C", "authenticationStatus": "Y", "authStatusReason": "", "challengeResultTransStatus": "", "XID": "1dd3cf75-92a7-4487-abb5-b1f3cdd68f3b", "AV": "MTIzNDU2Nzu5MDA5ODc2NTQzMjE=", "ECI": "05", "AVAlgorithm": "", "threeDsVersion": "2.2.0" }, "transDetails": { "authData": "", "authMethod": "02", "authTimeStamp": "202505131259", "acsID": "f688e45c-ff27-4ba6-a631-4b68df2dbf99" } }, "events": [ { "event": { "eventtype": "AUT", "eventamount": "0.00", "eventdate": "13/05/25 13:01:52", "eventARN": "", "eventID": "", "eventReferred": "" } } ], "buyer": { "name": "", "email": "" }, "risk": { "riskResponseCode": "", "riskResponseDescription": "" }, "customInfo": null, "alertCode": "", "alertDescription": "", "cvvPresent": "TRUE", "dcc": null, "maskedPAN": "", "paymentMethod": "VISA", "productType": "Credit", "token": "40G5LMXUQQ613101", "tokenExpiryMonth": "05", "tokenExpiryYear": "27", "tokenDetails": { "TokenValue": "40G5LMXUQQ613101", "TokenExpiryMonth": "05", "TokenExpiryYear": "27", "TokenProvider": "AXERVE", "CardDetails": { "CardSuffix": "3101", "CardExpiryMonth": "05", "CardExpiryYear": "27", "CardHolderName": null }, "CardAssets": { "CardArt": { "Type": null, "MediaContents": null, "Height": null, "Width": null }, "BrandLogo": { "Type": null, "MediaContents": null, "Height": null, "Width": null } } }, "fraudPrevention": { "check": "FALSE", "state": "", "description": "", "order": "" }, "automaticOperation": { "type": "CAN", "date": "07/06/25 00:00:00", "amount": "0.00" } } } ```