Web Components

Visualizza come Markdown

I Web Components integrano il pagamento direttamente nella pagina di checkout dell'esercente, senza iFrame né popup. Ogni componente è un elemento HTML nativo configurabile tramite attributi: riceve payment-id e payment-token generati lato server e gestisce l'intero flusso di pagamento, inclusi i redirect richiesti dall'autenticazione 3DS e dagli APM.

Prerequisiti

Per utilizzare i Web Components sono necessari:

uno shopLogin attivo rilasciato da Fabrick;
un backend che esegue la chiamata payment/create per ottenere paymentID e paymentToken;
la configurazione dei wallet, se si desidera mostrare Apple Pay o Google Pay (vedi Apple Pay e Google Pay).

Integrazione

L'integrazione si articola in quattro passi: caricamento dello script, creazione della sessione di pagamento lato server, montaggio del componente nella pagina e recupero dell'esito.

Passo 1 — Carica lo script

Includi lo script nell'<head> della pagina, utilizzando l'URL dell'ambiente in uso:

Sandbox: https://sandbox-web.axerve.com/orchestra/checkout/assets/elements/fbk-elements.js
Produzione: https://web.axerve.com/orchestra/checkout/assets/elements/fbk-elements.js

Passo 2 — Crea la sessione di pagamento

Esegui lato server la chiamata payment/create. La risposta contiene i due valori da passare al componente.

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

Response

{
  "error": {
    "code": "0",
    "description": "request correctly processed"
  },
  "payload": {
    "paymentToken": "f0419188-8a78-4918-913c-a491e4e78084",
    "paymentID": "1881129911957",
    "userRedirect": null,
    "qrCode": null
  }
}

Campo	Tipo	Descrizione
`paymentID`	`string`	Identificativo della transazione
`paymentToken`	`string`	Token di sessione temporaneo

API key

La chiamata payment/create va eseguita sempre lato server: richiede l'API key, che non deve mai essere esposta nel codice client. paymentID e paymentToken sono invece valori di sessione, destinati a essere passati al componente nella pagina.

Passo 3 — Configura e monta il componente

Lo shopLogin può essere impostato in due modi.

Tramite JavaScript, prima che il componente venga montato nel DOM:

window['fbk-elements'].shop = 'GESPAY12345';

Oppure tramite l'attributo shop-login, direttamente sul tag:

<fbk-checkout shop-login="GESPAY12345"></fbk-checkout>

Aggiungi il componente alla pagina, valorizzando gli attributi obbligatori payment-id e payment-token:

<fbk-checkout
  id="paymentComponent"
  payment-id="PAYMENT_ID"
  payment-token="PAYMENT_TOKEN">
</fbk-checkout>

In alternativa, gli attributi possono essere impostati tramite JavaScript dopo aver ottenuto i valori dal server:

const el = document.getElementById('paymentComponent');
el.setAttribute('payment-id', paymentID);
el.setAttribute('payment-token', paymentToken);

Dimensioni del componente

Per impostazione predefinita il componente occupa il 100% della larghezza del contenitore. Per definirne le dimensioni, racchiudilo in un <div> dimensionato oppure applica un attributo style o una regola CSS.

Passo 4 — Recupera l'esito

Il componente gestisce l'intero flusso, inclusi i redirect per l'autenticazione 3DS e verso gli APM.

Al termine del pagamento, Fabrick reindirizza il buyer alla URL di esito positivo o negativo configurata per la transazione e invia contestualmente una notifica server-to-server (S2S) con l'esito.

Esempio di URL di redirect e notifica S2S:

https://merchant-url.com?a=GESPAY12345&Status=OK&paymentID=1881129911957&paymentToken=f0419188-8a78-4918-913c-a491e4e78084

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 buyer alla URL di esito positivo, ma lo stato non è ancora definitivo: è 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 o ottenuto dalla URL di redirect o dalla notifica S2S.

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": "1881129911957",
        "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"
        }
    }
}

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, per l'esito positivo e per quello negativo.

Quando l'oggetto responseURLs è presente nella chiamata, il sistema applica solo per quella transazione le URL specificate nella richiesta, al posto di quelle configurate nel backoffice Gestpay. Se l'oggetto non è presente, vengono utilizzate le configurazioni del backoffice.

È possibile specificare anche solo una parte dei parametri: se ad esempio viene impostata solo la URL di notifica server-to-server, oppure solo una delle URL di redirect, il sistema sovrascrive unicamente i valori indicati e continua a utilizzare le altre URL configurate nel backoffice 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"
  }
}

Esempio completo

Una pagina di checkout minima, con lo script dell'ambiente sandbox e il componente <fbk-checkout>:

checkout.html
<!DOCTYPE html>
<html lang="it">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>Test Pagamento Web Component</title>

    <script>
      // Inizializzazione dopo il caricamento di fbk-elements.js
      function initFabrickElements() {
        console.log("Fabrick Web Components caricati correttamente");

        // Impostazione shopLogin, prima del montaggio del componente
        window['fbk-elements'].shop = "GESPAY12345";

        // Montaggio del componente quando la pagina è pronta
        if (document.readyState === "loading") {
          document.addEventListener("DOMContentLoaded", mountCheckout);
        } else {
          mountCheckout();
        }
      }

      // Creazione e montaggio del componente fbk-checkout
      function mountCheckout() {
        // Questi valori sono SOLO di esempio
        // In produzione devono arrivare dal backend (payment/create)
        const paymentID    = "1881129911957";
        const paymentToken = "f0419188-8a78-4918-913c-a491e4e78084";

        const component = document.createElement("fbk-checkout");
        component.setAttribute("payment-id", paymentID);
        component.setAttribute("payment-token", paymentToken);
        document.getElementById("payment-container").appendChild(component);
      }
    </script>

    <!-- Script Fabrick con onload -->
    <script
      src="https://sandbox-web.axerve.com/orchestra/checkout/assets/elements/fbk-elements.js"
      onload="initFabrickElements()">
    </script>
  </head>
  <body>
    <div id="payment-container"></div>
  </body>
</html>

Componenti disponibili

Componente	Metodi mostrati	Quando utilizzarlo
`<fbk-checkout>`	Tutti i metodi abilitati sullo shopLogin	Integrazione standard, con un unico componente per tutti i metodi
`<fbk-card>`	Carta e Click to Pay	Pagamento con carta senza Apple Pay e Google Pay
`<fbk-apple-pay>`	Solo Apple Pay	Pulsante Apple Pay standalone
`<fbk-google-pay>`	Solo Google Pay	Pulsante Google Pay standalone

Componente consigliato

Per la maggior parte delle integrazioni è consigliato <fbk-checkout>: presenta in un'unica interfaccia i metodi di pagamento abilitati e si aggiorna automaticamente quando Fabrick ne aggiunge di nuovi.

`<fbk-checkout>`

Presenta tutti i metodi di pagamento disponibili in un'unica interfaccia e gestisce la selezione del metodo da parte del buyer. I nuovi metodi introdotti da Fabrick che non richiedono campi obbligatori vengono mostrati automaticamente.

<fbk-checkout
  payment-id="PAYMENT_ID"
  payment-token="PAYMENT_TOKEN"
  layout="horizontal"
  apple-button-style="black"
  apple-button-type="pay"
  google-button-style="black"
  google-button-type="pay">
</fbk-checkout>

Attributo	Valori	Default	Descrizione
`layout`	`horizontal`, `vertical`	`horizontal`	Struttura grafica del form carta
`apple-button-style`	`black`, `white`, `white-outline`	`black`	Aspetto del pulsante Apple Pay
`apple-button-type`	`plain`, `buy`, `pay`	`plain`	Etichetta del pulsante Apple Pay
`google-button-style`	`black`, `white`	`black`	Aspetto del pulsante Google Pay
`google-button-type`	`plain`, `buy`, `pay`	`plain`	Etichetta del pulsante Google Pay

Componente fbk-checkout

Wallet nel componente

Per mostrare Apple Pay e Google Pay in <fbk-checkout> è necessario completare la configurazione dei due wallet (vedi Apple Pay e Google Pay).

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 in <fbk-checkout>.

`paymentType`	Comportamento di `<fbk-checkout>`
Non valorizzato	Mostra tutti i metodi abilitati per lo `shopLogin` nel backoffice Gestpay che non richiedono campi obbligatori
Più metodi, ad esempio `["FABRICKPASS", "CREDITCARD"]`	Mostra la selezione limitata ai metodi indicati
Solo `["CREDITCARD"]`	Mostra la selezione con la carta e i wallet abilitati
Un solo APM, ad esempio `["FABRICKPASS"]`	Non mostra la selezione: se il metodo prevede un redirect, il buyer viene reindirizzato direttamente al servizio; in caso contrario, completa il pagamento direttamente nel componente

Metodi con campi obbligatori

Alcuni metodi di pagamento richiedono campi obbligatori nella chiamata payment/create. Questi metodi vengono presentati in <fbk-checkout> solo se la chiamata include i campi previsti; in caso contrario non vengono mostrati. 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.

Non valorizzato
Più metodi
Solo carta
Un solo APM

Il campo paymentType non è presente: <fbk-checkout> mostra 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"
}

Sono indicati più metodi di pagamento, ad esempio Pay By Bank e carta: <fbk-checkout> mostra la selezione limitata ai soli metodi indicati.

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", "CREDITCARD"]
}

fbk-checkout con selezione limitata a Pay By Bank e carta

È indicato solo CREDITCARD: <fbk-checkout> mostra la selezione con la carta e i wallet abilitati.

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

Carte e wallet

Con il campo paymentType valorizzato con il tag CREDITCARD, in <fbk-checkout> oltre al pagamento con carta vengono mostrati anche i wallet abilitati, come Apple Pay, Google Pay e Click to Pay.

fbk-checkout con carta e wallet

È indicato un solo metodo di pagamento alternativo, ad esempio FABRICKPASS: <fbk-checkout> non mostra la selezione. Se il metodo prevede un redirect, il buyer viene reindirizzato direttamente al servizio; in caso contrario, completa il pagamento direttamente nel componente.

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

`<fbk-card>`

Raccoglie i dati della carta e mostra anche Click to Pay, se abilitato sullo shopLogin. È indicato quando si desidera presentare il pagamento con carta senza Apple Pay e Google Pay.

<fbk-card
  payment-id="PAYMENT_ID"
  payment-token="PAYMENT_TOKEN"
  layout="horizontal">
</fbk-card>

Attributo	Valori	Default	Descrizione
`layout`	`horizontal`, `vertical`	`horizontal`	Struttura grafica del form carta

layout="horizontal"

fbk-card con layout orizzontale

layout="vertical"

fbk-card con layout verticale

`<fbk-apple-pay>`

Mostra un pulsante Apple Pay standalone, la cui etichetta si adatta automaticamente alla lingua del browser. Il pagamento è disponibile su tutti i browser, anche da dispositivi non Apple.

Configurazione richiesta

Per mostrare il pulsante è necessario completare la configurazione di Apple Pay per i Web Components.

<fbk-apple-pay
  payment-id="PAYMENT_ID"
  payment-token="PAYMENT_TOKEN"
  button-style="black"
  button-type="pay">
</fbk-apple-pay>

Attributo	Valori	Default	Descrizione
`button-style`	`black`, `white`, `white-outline`	`black`	Aspetto del pulsante
`button-type`	`plain`, `buy`, `pay`	`plain`	Etichetta del pulsante

button-style="black"

Pulsante Apple Pay nero

button-style="white"

Pulsante Apple Pay bianco

Esempio con localizzazione italiana:

Pulsante Apple Pay con localizzazione italiana

Per i pagamenti da dispositivi non Apple viene mostrato un QR Code che consente di completare il pagamento tramite un dispositivo Apple esterno: dopo la scansione, il flusso viene avviato sul dispositivo e la transazione processata da Fabrick.

QR Code Apple Pay per il pagamento da dispositivo non Apple

Se il QR Code scade, è possibile generarne uno nuovo per la stessa transazione cliccando su Ricevi nuovo codice.

Rigenerazione del QR Code Apple Pay scaduto

`<fbk-google-pay>`

Mostra un pulsante Google Pay standalone.

Configurazione richiesta

Per mostrare il pulsante è necessario completare la configurazione di Google Pay per i Web Components.

<fbk-google-pay
  payment-id="PAYMENT_ID"
  payment-token="PAYMENT_TOKEN"
  button-style="black"
  button-type="pay">
</fbk-google-pay>

Attributo	Valori	Default	Descrizione
`button-style`	`black`, `white`	`black`	Aspetto del pulsante
`button-type`	`plain`, `buy`, `pay`	`plain`	Etichetta del pulsante

button-style="black"

Pulsante Google Pay nero

button-style="white"

Pulsante Google Pay bianco

Apple Pay e Google Pay

Per mostrare Apple Pay e Google Pay nei Web Components è necessaria una configurazione dedicata per ciascun wallet, descritta nella pagina del metodo di pagamento:

Errori non bloccanti

Durante il flusso il componente può emettere l'evento fbk-elements-error, che segnala errori che non interrompono la transazione ma che possono essere mostrati al buyer.

Il dettaglio dell'evento ha la seguente struttura:

{
  "code": "",
  "title": "",
  "message": ""
}

Campo	Tipo	Descrizione
`code`	`string`	Codice dell'errore
`title`	`string`	Titolo breve dell'errore
`message`	`string`	Descrizione dettagliata dell'errore

Per intercettare e gestire l'evento nella pagina, registra un listener:

window.addEventListener('fbk-elements-error', event => {
  const { code, title, message } = event.detail;
  // Gestione dell'errore, ad esempio con un messaggio al buyer
});

Checklist di go-live

Prima di attivare l'integrazione in produzione, verifica i seguenti punti.

Script e configurazione

Lo script punta all'URL di produzione, non a quello sandbox.
Lo shopLogin è impostato prima che il componente venga montato nel DOM.
La pagina di esito esegue la chiamata GET /payment/detail con paymentID e paymentToken e gestisce tutti gli stati della transazione, inclusi i pagamenti rifiutati e le sessioni scadute.

Sicurezza

La chiamata payment/create è eseguita lato server e l'API key non è esposta nel codice client.

Wallet

La configurazione di Apple Pay e Google Pay è completata per l'ambiente di produzione (vedi Apple Pay e Google Pay).

Prerequisiti​

Integrazione​

Passo 1 — Carica lo script​

Passo 2 — Crea la sessione di pagamento​

Passo 3 — Configura e monta il componente​

Passo 4 — Recupera l'esito​

Pagina di conferma dell'ordine e notifica server-to-server​

Esempio completo​

Componenti disponibili​

<fbk-checkout>​

Logiche di presentazione dei metodi di pagamento​

<fbk-card>​

<fbk-apple-pay>​

<fbk-google-pay>​

Apple Pay e Google Pay​

Errori non bloccanti​

Checklist di go-live​

Prerequisiti

Integrazione

Passo 1 — Carica lo script

Passo 2 — Crea la sessione di pagamento

Passo 3 — Configura e monta il componente

Passo 4 — Recupera l'esito

Pagina di conferma dell'ordine e notifica server-to-server

Esempio completo

Componenti disponibili

`<fbk-checkout>`

Logiche di presentazione dei metodi di pagamento

`<fbk-card>`

`<fbk-apple-pay>`

`<fbk-google-pay>`

Apple Pay e Google Pay

Errori non bloccanti

Checklist di go-live