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.

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.

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
le funzionalità di Tokenizzazione
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 pagmento (APM), utilizzando l'oggetto paymentType è possibile specificare nella chiamata payment/create quali metodi presentare sulla pagina, se viene specifiato solo un metodo di pagamento il sistema reindirizzerà il buyer direttamente verso il servizio senza passare dalla pagina di selezione.

Nel caso in cui si desidera invece riportare il buyer alla pagina dedicata all’inserimento dei dati della carta offerta da Farbick senza passare dalla pagina di selezione del metodo è necessario specificare in chiamata il paymentType CREDITCARD, specificando questo oggetto, se abilitati, verranno anche mostrate le modalità di pagamento tramite wallet, come ApplePay, GooglePay e Click to Pay.

Se in chiamata non viene utilizzato l'oggetto paymentType, in base alla configurazioni impostate sul backoffice di gestpay, nella pagina di pagamento verranno mostrati tutti i metodi di pagamento abilitati per lo shopLogin utilizzato e il buyer potrà scegliere con quale metodo di pagamento procedere.

Elenco completo dei paymentType

I possibili valori di paymentType sono disponibili alla sezione payment type codes o in alternativa è possibile utilizzare l'endpoint GET shop/paymentMethods per verificare in tempo reale i metodi di pagamento abilitati per lo shopLogin utilizzato e filtrare la risposta per payload.paymentMethod.paymentType.

Di seguito un esempio di richiesta in cui viene specificato solo il pagamento con carta, in questo al buyer verrà presentata la pagina dedicata all'inserimento dei dati della carta senza passare dalla pagina di selezione del metodo.

Request

POST /api/v1/payment/create
Host (sandbox): sandbox.gestpay.net
Host (produzione): ecomms2s.sella.it
Authorization: apikey ****************
Content-Type: application/json

{
  "shopLogin": "GESPAY12345",
  "amount": "100",
  "currency": "EUR",
  "shopTransactionID": "FBK_OrderID",
  "paymentType":["FABRICKPASS"]
}

Se nella richiesta vengono specificati più metodi di pagamento, ad esempio CREDITCARD e FABRICKPASS, al buyer verrà mostrata la pagina di selezione del metodo di pagamento, nella quale potrà scegliere uno dei metodi indicati nella chiamata.

Request

POST /api/v1/payment/create
Host (sandbox): sandbox.gestpay.net
Host (produzione): ecomms2s.sella.it
Authorization: apikey ****************
Content-Type: application/json

{
  "shopLogin": "GESPAY12345",
  "amount": "100",
  "currency": "EUR",
  "shopTransactionID": "FBK_OrderID",
  "paymentType":["CREDITCARD", "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

POST /api/v1/payment/create
Host (sandbox): sandbox.gestpay.net
Host (produzione): ecomms2s.sella.it
Authorization: apikey ****************
Content-Type: application/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"
  }
}

Una volta ottenuti PaymentToken e PaymentID in risposta alla chiamata payment/create, è possibile procedere con l’integrazione della soluzione Lightbox.

1. JavaScript Fabrick (CDN)

Il primo passaggio consiste nell’importare la libreria JavaScript dedicata:

Sandbox: https://sandbox.gestpay.net/pagam/javascript/axerve.js
Produzione: https://ecomm.sella.it/pagam/javascript/axerve.js

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:

<!DOCTYPE html>
  <html lang="it">
    <head>
      <meta charset="UTF-8" />
      <title>Test Pagamento Lightbox</title>

      <script>
        // Inizializzazione dopo caricamento axerve.js
        function initFabrickLightbox() {
          console.log("Fabrick Lightbox SDK caricato correttamente");

          // Impostazione shopLogin
          axerve.lightBox.shop = "GESPAY12345";

          // Questi valori sono SOLO di esempio
          // In produzione devono arrivare dal backend
          window.paymentID    = "1610469726440";
          window.paymentToken = "c7d0cb20-0d82-4f8a-b54b-18f1b3a3b82f";
        }
      </script>

      <!-- Script Fabrick con onload -->
      <script 
        src="https://sandbox.gestpay.net/pagam/javascript/axerve.js" 
        onload="initFabrickLightbox()">
      </script>
    </head>
    <body>
      <button onclick="axerve.lightBox.open(paymentID, paymentToken)">
        Avvia Pagamento
      </button>
    </body>
  </html>

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:

<!DOCTYPE html>
  <html lang="it">
    <head>
      <meta charset="UTF-8" />
      <title>Test Pagamento Lightbox</title>

      <script>
        // Inizializzazione dopo caricamento axerve.js
        function initFabrickLightbox() {
          console.log("Fabrick Lightbox SDK caricato correttamente");

          // Impostazione shopLogin (obbligatorio)
          axerve.lightBox.shop = "GESPAY12345";

          // Questi valori sono SOLO di esempio
          // In produzione devono arrivare dal backend
          window.paymentID    = "1610469726440";
          window.paymentToken = "c7d0cb20-0d82-4f8a-b54b-18f1b3a3b82f";
        }

        // Callback definita a livello globale per essere accessibile dall'onclick
        function handleCallback(response) {
          console.log(response);
          /* esempio di risposta:
          {
            "error": { "code": null, "description": null },
            "status": "OK",
            "responseURL": "https://redirect-url.com",
            "paymentId": "1403159914604"
          }
          */
        }
      </script>

      <!-- Script Fabrick con onload -->
      <script 
        src="https://sandbox.gestpay.net/pagam/javascript/axerve.js" 
        onload="initFabrickLightbox()">
      </script>
    </head>
    <body>
      <button onclick="axerve.lightBox.open(paymentID, paymentToken, handleCallback)">
        Avvia Pagamento
      </button>
    </body>
  </html>

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, oppure se nella richiesta payment/create è stato specificato un solo metodo APM, 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.

Conlcusione 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: pagamento non è ancora inziato (XX)

Esempio di chiamata per verificare lo stato della transazione tramite paymentID.

Request

GET api/v1/payment/detail/{paymentID}
Host (sandbox): sandbox.gestpay.net
Host (produzione): ecomms2s.sella.it
Authorization: apikey **************** (or) PaymentToken: c7d0cb20-0d82-4f8a-b54b-18f1b3a3b82f
Content-Type: application/json

Response

{
    "error": {
        "code": "0",
        "description": "request correctly processed"
    },
    "payload": {
        "transactionType": "detail",
        "transactionResult": "APPROVED",
        "transactionState": "AUT",
        "transactionErrorCode": "0",
        "transactionErrorDescription": "Transazione correttamente effettuata",
        "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"
        }
    }
}

Inizializzazione pagamento​

Logiche di Presentazione dei Metodi di Pagamento​

Pagina di conferma dell’ordine e notifica server to server​

Integrazione Lightbox​

1. JavaScript Fabrick (CDN)​

2. Impostazione variabili​

3. Presentazione pagina di pagamento​

Redirect automatico​

Callback​

Comportamento con metodi alternativi (APM)​

Conlcusione transazione e Notifica del Pagamento​

Inizializzazione pagamento

Logiche di Presentazione dei Metodi di Pagamento

Pagina di conferma dell’ordine e notifica server to server

Integrazione Lightbox

1. JavaScript Fabrick (CDN)

2. Impostazione variabili

3. Presentazione pagina di pagamento

Redirect automatico

Callback

Comportamento con metodi alternativi (APM)

Conlcusione transazione e Notifica del Pagamento