Web Components

I Web Components incorporano il pagamento direttamente nella tua pagina di checkout, senza iFrame né popup. Ogni componente è un elemento HTML nativo che configuri tramite attributi: gli passi payment-id e payment-token generati dal tuo server e lui porta a termine l'intero flusso, inclusi i redirect richiesti dall'autenticazione 3DS o dagli APM come PayPal e Klarna.

Prima di iniziare

Assicurati di avere:

uno shopLogin attivo rilasciato da Fabrick;
un backend in grado di chiamare POST /payment/create per ottenere paymentID e paymentToken;
un dominio certificato, se vuoi mostrare Apple Pay o Google Pay (vedi Certificazione domini).

Carica lo script

Includi lo script nell'<head> della pagina, usando l'URL dell'ambiente su cui stai lavorando.

Sandbox
Produzione

<script src="https://sandbox-web.axerve.com/orchestra/checkout/assets/elements/fbk-elements.js"></script>

<script src="https://web.axerve.com/orchestra/checkout/assets/elements/fbk-elements.js"></script>

Crea la sessione di pagamento

Dal tuo server, chiama POST /payment/create. La risposta contiene i due valori che passerai al componente.

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

warning

Genera sempre paymentID e paymentToken lato server. Non esporli mai nel codice client.

Configura e monta il componente

Imposta il tuo shopLogin in uno dei due modi.

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

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

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

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

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

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

In alternativa, imposta gli attributi via JavaScript dopo aver ottenuto i token:

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

Il componente occupa per impostazione predefinita il 100% della larghezza del contenitore. Puoi definirne le dimensioni racchiudendolo in un <div> dimensionato, con un attributo style, oppure tramite una regola CSS.

Recupera l'esito

Il componente porta a termine l'intero flusso, redirect di 3DS e APM inclusi. Non devi registrare alcuna callback.

Quando il pagamento si conclude, Fabrick invia una notifica server-to-server e reindirizza l'utente alla tua pagina di esito. A partire da uno di questi due eventi, chiama GET /payment/detail con paymentID e paymentToken per leggere i dettagli completi della transazione.

Errori non bloccanti

Durante il flusso il componente può emettere l'evento fbk-elements-error. Segnala errori che non interrompono la transazione ma che puoi voler mostrare all'utente.

Il dettaglio dell'evento ha questa struttura:

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

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

Registra un listener per intercettarlo e gestirlo nella pagina:

window.addEventListener('fbk-elements-error', event => {
  const { code, title, message } = event.detail;
  // Gestisci l'errore, ad esempio mostrando un messaggio all'utente
});

Componenti

Componente consigliato

Per la maggior parte delle integrazioni usa <fbk-checkout>: include tutti i metodi di pagamento e si aggiorna da solo quando Fabrick ne aggiunge di nuovi.

`<fbk-checkout>`

Presenta tutti i metodi di pagamento disponibili in un'unica interfaccia e gestisce per te la selezione del metodo. I nuovi metodi aggiunti da Fabrick compaiono in automatico, senza modifiche al tuo codice.

<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

`<fbk-card>`

Raccoglie i dati della carta per pagamenti con carte di credito e debito. Usalo quando vuoi presentare il solo pagamento con carta, senza wallet.

<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. Il pulsante compare in Safari sui dispositivi iOS, iPadOS e macOS supportati e la sua etichetta si adatta automaticamente alla lingua del browser.

<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

informazioni

Richiede la certificazione del dominio Apple Pay.

`<fbk-google-pay>`

Mostra un pulsante Google Pay standalone.

<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

informazioni

Richiede la certificazione del dominio Google Pay.

Certificazione domini

Apple Pay e Google Pay richiedono la verifica del dominio prima di essere attivati in produzione. La procedura è diversa per i due provider.

Apple Pay

Ospita sul tuo dominio il file di domain association fornito da Fabrick, all'esatto percorso richiesto da Apple.

1. Scarica il file:

https://web.fabrick.com/.well-known/apple-developer-merchantid-domain-association

2. Pubblicalo su:

https://{tuo-dominio}/.well-known/apple-developer-merchantid-domain-association

Il file deve essere raggiungibile pubblicamente, senza autenticazione e senza redirect.

3. Comunica il dominio al tuo referente Fabrick per completare la registrazione.

Google Pay

Google gestisce la certificazione tramite il tuo account.

1. Accedi alla Google Pay & Wallet Console e crea un Merchant ID.

2. Registra il dominio e completa la verifica di Google. Quando richiesto, seleziona PSP: Axerve come tipo di integrazione.

3. Fornisci il Merchant ID al tuo referente Fabrick, che lo assocerà al tuo account.

Per i dettagli, consulta la documentazione ufficiale Google Pay.

Esempio completo

checkout.html
<!doctype html>
<html lang="it">
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <script src="https://sandbox-web.axerve.com/orchestra/checkout/assets/elements/fbk-elements.js"></script>
</head>
<body>
  <fbk-checkout
    shop-login="GESPAY12345"
    payment-id="12345678910"
    payment-token="1234ea321-aaaa-bbbb-cccc-752ca0b8cb5b">
  </fbk-checkout>
</body>
</html>

Checklist di go-live

Verifica questi punti prima di attivare l'integrazione in produzione.

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 chiama GET /payment/detail con paymentID e paymentToken e gestisce tutti gli stati della transazione, inclusi i pagamenti rifiutati e le sessioni scadute.

Sicurezza

paymentID e paymentToken sono generati lato server e non esposti nel codice client.

Wallet

Il dominio è certificato per Apple Pay e il file .well-known è raggiungibile pubblicamente.
Il Merchant ID Google è stato comunicato al referente Fabrick e associato all'account.

Prima di iniziare​

Carica lo script​

Crea la sessione di pagamento​

Configura e monta il componente​

Recupera l'esito​

Errori non bloccanti​

Componenti​

<fbk-checkout>​

<fbk-card>​

<fbk-apple-pay>​

<fbk-google-pay>​

Certificazione domini​

Apple Pay​

Google Pay​

Esempio completo​

Checklist di go-live​