Web Components

View as Markdown

Web Components embed the payment directly in the merchant's checkout page, with no iFrames or pop-ups. Each component is a native HTML element configured through attributes: it receives the payment-id and payment-token generated on the server side and handles the entire payment flow, including the redirects required by 3DS authentication and by APMs.

Prerequisites

To use Web Components you need:

an active shopLogin issued by Fabrick;
a backend able to execute the payment/create call to obtain the paymentID and paymentToken;
the wallet configuration, if you want to show Apple Pay or Google Pay (see Apple Pay and Google Pay).

Integration

The integration consists of four steps: loading the script, creating the payment session on the server side, mounting the component in the page and retrieving the outcome.

Step 1 — Load the script

Include the script in the <head> of the page, using the URL of the environment in use:

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

Step 2 — Create the payment session

Perform the payment/create call on the server side. The response contains the two values to pass to the component.

Request

POST /api/v1/payment/create
Host (sandbox): sandbox.gestpay.net
Host (production): 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
  }
}

Field	Type	Description
`paymentID`	`string`	Identifier of the transaction
`paymentToken`	`string`	Temporary session token

API key

The payment/create call must always be performed on the server side: it requires the API key, which must never be exposed in the client code. The paymentID and paymentToken, on the other hand, are session values meant to be passed to the component in the page.

Step 3 — Configure and mount the component

The shopLogin can be set in two ways.

Through JavaScript, before the component is mounted in the DOM:

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

Or through the shop-login attribute, directly on the tag:

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

Add the component to the page, populating the mandatory payment-id and payment-token attributes:

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

Alternatively, the attributes can be set through JavaScript once the values have been obtained from the server:

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

Component size

By default the component takes up 100% of the width of its container. To set its size, wrap it in a sized <div> or apply a style attribute or a CSS rule.

Step 4 — Retrieve the outcome

The component handles the entire flow, including the redirects for 3DS authentication and to APMs.

At the end of the payment, Fabrick redirects the buyer to the positive or negative outcome URL configured for the transaction and, at the same time, sends a server-to-server (S2S) notification with the outcome.

Example of redirect URL and S2S notification:

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

The redirect URL and the S2S notification contain the Status parameter, which immediately identifies the status of the payment. The possible values are:

OK: payment completed with a positive outcome
KO: payment completed with a negative outcome
XX: payment on hold, awaiting the final outcome

Suspended status (XX)

The XX status is used only by some alternative payment methods (APMs) and is returned when the outcome is asynchronous. In this scenario Fabrick redirects the buyer to the positive outcome URL, but the status is not yet final: you need to wait for a subsequent S2S notification communicating the final outcome (OK or KO).

If you receive the XX status, do not ship the goods or deliver the service.
Wait for the S2S notification communicating the final outcome of the payment.

To check the outcome or the updated status of the transaction you can use the GET payment/detail endpoint, passing as a parameter the paymentID returned by the payment/create call or obtained from the redirect URL or the S2S notification.

The response contains the transactionResult parameter, which indicates the status of the payment. The possible values are:

AUTHENTICATED: payment authenticated (OK)
APPROVED: payment approved (OK)
DECLINED: payment declined (KO)
PENDING: payment awaiting confirmation (XX)
WAITING: payment in progress (XX)
UNSUBMITTED: the payment has not started yet (XX)

Example of a call to check the status of the transaction through the paymentID.

Request

GET /api/v1/payment/detail/{paymentID}
Host (sandbox): sandbox.gestpay.net
Host (production): 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"
        }
    }
}

Order confirmation page and server-to-server notification

When creating the request you can use the responseURLs object to dynamically define the redirect URLs and the server-to-server notification URL that the system will use at the end of the transaction, for both positive and negative outcomes.

When the responseURLs object is included in the call, the system applies the URLs specified in the request for that transaction only, instead of those configured in the Gestpay back office. If the object is not present, the back office settings are used.

You can also specify only some of the parameters: if, for example, only the server-to-server notification URL or only one of the redirect URLs is set, the system overrides only the values provided and keeps using the other URLs configured in the Gestpay back office.

Below is an example of a request defining all the redirect URLs and the server-to-server notification URL.

Request

POST /api/v1/payment/create
Host (sandbox): sandbox.gestpay.net
Host (production): 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"
  }
}

Complete example

A minimal checkout page, with the sandbox script and the <fbk-checkout> component:

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

    <script>
      // Initialisation once fbk-elements.js has loaded
      function initFabrickElements() {
        console.log("Fabrick Web Components loaded correctly");

        // Set the shopLogin before the component is mounted
        window['fbk-elements'].shop = "GESPAY12345";

        // Mount the component once the page is ready
        if (document.readyState === "loading") {
          document.addEventListener("DOMContentLoaded", mountCheckout);
        } else {
          mountCheckout();
        }
      }

      // Create and mount the fbk-checkout component
      function mountCheckout() {
        // These values are for illustration ONLY
        // In production they must come from the 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>

    <!-- Fabrick script with 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>

Available components

Component	Methods shown	When to use it
`<fbk-checkout>`	All the methods enabled on the shopLogin	Standard integration, with a single component for all methods
`<fbk-card>`	Card and Click to Pay	Card payment without Apple Pay and Google Pay
`<fbk-apple-pay>`	Apple Pay only	Standalone Apple Pay button
`<fbk-google-pay>`	Google Pay only	Standalone Google Pay button

Recommended component

For most integrations <fbk-checkout> is recommended: it presents the enabled payment methods in a single interface and updates automatically when Fabrick adds new ones.

`<fbk-checkout>`

Shows all the available payment methods in a single interface and handles the buyer's choice of method. New payment methods introduced by Fabrick that do not require mandatory input fields are automatically displayed.

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

Attribute	Values	Default	Description
`layout`	`horizontal`, `vertical`	`horizontal`	Layout of the card form
`apple-button-style`	`black`, `white`, `white-outline`	`black`	Appearance of the Apple Pay button
`apple-button-type`	`plain`, `buy`, `pay`	`plain`	Label of the Apple Pay button
`google-button-style`	`black`, `white`	`black`	Appearance of the Google Pay button
`google-button-type`	`plain`, `buy`, `pay`	`plain`	Label of the Google Pay button

fbk-checkout component

Wallets in the component

To show Apple Pay and Google Pay in <fbk-checkout>, the configuration of the two wallets must be completed (see Apple Pay and Google Pay).

Payment method presentation logic

When creating the request, if the shopLogin is enabled for more than one payment method (APM), you can use the paymentType field in the payment/create call to specify which methods to present to the buyer in <fbk-checkout>.

`paymentType`	`<fbk-checkout>` behaviour
Not populated	Shows all the methods enabled for the `shopLogin` in the Gestpay back office that do not require mandatory fields
More than one method, for example `["FABRICKPASS", "CREDITCARD"]`	Shows the selection limited to the methods specified
`["CREDITCARD"]` only	Shows the selection with the card and the enabled wallets
A single APM, for example `["FABRICKPASS"]`	Skips the selection: if the method requires a redirect, the buyer is taken straight to the service; if not, they complete the payment directly in the component

Methods with mandatory fields

Some payment methods require mandatory fields in the payment/create call. These methods are presented in <fbk-checkout> only if the call includes the required fields; otherwise they are not shown. The fields required by each method are listed on the method's page.

Full list of paymentType values

The possible paymentType values are listed in the payment type codes section. Alternatively, you can use the GET shop/paymentMethods endpoint to check in real time the payment methods enabled for the shopLogin used, filtering the response by payload.paymentMethod.paymentType.

Below is an example request for each case.

Not populated
More than one method
Card only
A single APM

The paymentType field is omitted: <fbk-checkout> shows all the methods enabled for the shopLogin that do not require mandatory fields.

Request

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

{
  "shopLogin": "GESPAY12345",
  "amount": "100",
  "currency": "EUR",
  "shopTransactionID": "FBK_OrderID"
}

More than one payment method is specified, for example Pay By Bank and card: <fbk-checkout> shows the selection limited to the methods specified.

Request

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

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

fbk-checkout with the selection limited to Pay By Bank and card

Only CREDITCARD is specified: <fbk-checkout> shows the selection with the card and the enabled wallets.

Request

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

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

Cards and wallets

When the paymentType field is populated with the CREDITCARD tag, <fbk-checkout> shows the enabled wallets, such as Apple Pay, Google Pay and Click to Pay, alongside card payment.

fbk-checkout with card and wallets

A single alternative payment method is specified, for example FABRICKPASS: <fbk-checkout> skips the selection. If the method requires a redirect, the buyer is taken straight to the service; if not, they complete the payment directly in the component.

Request

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

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

`<fbk-card>`

Collects the card details and also shows Click to Pay, if enabled on the shopLogin. Use it when you want to offer card payment without Apple Pay and Google Pay.

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

Attribute	Values	Default	Description
`layout`	`horizontal`, `vertical`	`horizontal`	Layout of the card form

layout="horizontal"

fbk-card with horizontal layout

layout="vertical"

fbk-card with vertical layout

`<fbk-apple-pay>`

Shows a standalone Apple Pay button, whose label adapts automatically to the browser language. The payment is available on all browsers, including on non-Apple devices.

Configuration required

To show the button, the Apple Pay configuration for Web Components must be completed.

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

Attribute	Values	Default	Description
`button-style`	`black`, `white`, `white-outline`	`black`	Appearance of the button
`button-type`	`plain`, `buy`, `pay`	`plain`	Label of the button

button-style="black"

Black Apple Pay button

button-style="white"

White Apple Pay button

Example with Italian localisation:

Apple Pay button with Italian localisation

For payments from non-Apple devices, a QR Code is shown that lets the buyer complete the payment with an external Apple device: after scanning, the flow starts on the device and the transaction is processed by Fabrick.

Apple Pay QR Code for payment from a non-Apple device

If the QR Code expires, you can generate a new one for the same transaction by clicking Ricevi nuovo codice.

Regenerating an expired Apple Pay QR Code

`<fbk-google-pay>`

Shows a standalone Google Pay button.

Configuration required

To show the button, the Google Pay configuration for Web Components must be completed.

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

Attribute	Values	Default	Description
`button-style`	`black`, `white`	`black`	Appearance of the button
`button-type`	`plain`, `buy`, `pay`	`plain`	Label of the button

button-style="black"

Black Google Pay button

button-style="white"

White Google Pay button

Apple Pay and Google Pay

To show Apple Pay and Google Pay in Web Components, each wallet requires a dedicated configuration, described on the page of the payment method:

Non-blocking errors

During the flow the component may emit the fbk-elements-error event, which reports errors that do not interrupt the transaction but may be shown to the buyer.

The event detail has the following structure:

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

Field	Type	Description
`code`	`string`	Error code
`title`	`string`	Short title of the error
`message`	`string`	Detailed description of the error

To intercept and handle the event in the page, register a listener:

window.addEventListener('fbk-elements-error', event => {
  const { code, title, message } = event.detail;
  // Handle the error, for example by showing a message to the buyer
});

Go-live checklist

Before activating the integration in production, check the following points.

Script and configuration

The script points to the production URL, not the sandbox one.
The shopLogin is set before the component is mounted in the DOM.
The outcome page performs the GET /payment/detail call with the paymentID and paymentToken and handles all transaction statuses, including declined payments and expired sessions.

Security

The payment/create call is performed on the server side and the API key is not exposed in the client code.

Wallets

The Apple Pay and Google Pay configuration is completed for the production environment (see Apple Pay and Google Pay).

Prerequisites​

Integration​

Step 1 — Load the script​

Step 2 — Create the payment session​

Step 3 — Configure and mount the component​

Step 4 — Retrieve the outcome​

Order confirmation page and server-to-server notification​

Complete example​

Available components​

<fbk-checkout>​

Payment method presentation logic​

<fbk-card>​

<fbk-apple-pay>​

<fbk-google-pay>​

Apple Pay and Google Pay​

Non-blocking errors​

Go-live checklist​

Prerequisites

Integration

Step 1 — Load the script

Step 2 — Create the payment session

Step 3 — Configure and mount the component

Step 4 — Retrieve the outcome

Order confirmation page and server-to-server notification

Complete example

Available components

`<fbk-checkout>`

Payment method presentation logic

`<fbk-card>`

`<fbk-apple-pay>`

`<fbk-google-pay>`

Apple Pay and Google Pay

Non-blocking errors

Go-live checklist