Passa al contenuto principale

Lightbox

Visualizza come Markdown

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

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:

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.

paymentTypeComportamento della Lightbox
Non valorizzatoMostra 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. 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.

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

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"
}

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"
  }
}

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 <script> che punta direttamente all'URL Fabrick dell'ambiente utilizzato:

  • Sandbox: https://sandbox.gestpay.net/pagam/javascript/axerve.js
  • Produzione: https://ecomm.sella.it/pagam/javascript/axerve.js
<script src="https://ecomm.sella.it/pagam/javascript/axerve.js"></script>
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:

    <!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 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

GET /api/v1/payment/detail/{paymentID}
Host (sandbox): sandbox.gestpay.net
Host (produzione): ecomms2s.sella.it
Authorization: apikey ****************
Content-Type: application/json

Response

{
    "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"
        }
    }
}