---
title: "Web Components"
description: "Embed the payment in your checkout page with Fabrick Web Components: cards, wallets and alternative payment methods as native HTML elements, with no iFrames or pop-ups."
url: "https://docs.fabrick.com/en/payment-hub-and-orchestra/ecommerce/integration-methods/web-component/"
language: "en"
---

# Web Components

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](https://docs.fabrick.com/en/payment-hub-and-orchestra/ecommerce/integration-methods/web-component/#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**

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

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

**Response**

```json
{
  "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:

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

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

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

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

```html
<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:

```js
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**

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

**Response**

```json
{
    "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**

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

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

```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>`](https://docs.fabrick.com/en/payment-hub-and-orchestra/ecommerce/integration-methods/web-component/#fbk-checkout)     | All the methods enabled on the shopLogin | Standard integration, with a single component for all methods |
| [`<fbk-card>`](https://docs.fabrick.com/en/payment-hub-and-orchestra/ecommerce/integration-methods/web-component/#fbk-card)             | Card and Click to Pay                    | Card payment without Apple Pay and Google Pay                 |
| [`<fbk-apple-pay>`](https://docs.fabrick.com/en/payment-hub-and-orchestra/ecommerce/integration-methods/web-component/#fbk-apple-pay)   | Apple Pay only                           | Standalone Apple Pay button                                   |
| [`<fbk-google-pay>`](https://docs.fabrick.com/en/payment-hub-and-orchestra/ecommerce/integration-methods/web-component/#fbk-google-pay) | Google Pay only                          | Standalone Google Pay button                                  |

> **Recommended component**
>
> For most integrations [`<fbk-checkout>`](https://docs.fabrick.com/en/payment-hub-and-orchestra/ecommerce/integration-methods/web-component/#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.

```html
<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](https://docs.fabrick.com/en/assets/images/fbk-checkout-144362eb2494b3fa68e5d33fb6718be6.png)

> **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](https://docs.fabrick.com/en/payment-hub-and-orchestra/ecommerce/integration-methods/web-component/#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](https://api.paymentorchestra.fabrick.com/#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**

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

**Request**

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

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

**More than one method**

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

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

```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](https://docs.fabrick.com/en/assets/images/fbk-checkout-3-cac710175d89344ac2480cf5211f9641.png)

**Card only**

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

**Request**

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

```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](https://docs.fabrick.com/en/assets/images/fbk-checkout-2-c6cbf0f225b0beb2141542bea2f91fd3.png)

**A single APM**

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

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

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

```html
<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](https://docs.fabrick.com/en/assets/images/card-horizontal-67d65aacb6de287988472e73828e0821.png)

`layout="vertical"`

![fbk-card with vertical layout](https://docs.fabrick.com/en/assets/images/card-vertical-1074847761bbca9368ec1cfb679a7495.png)

---

### `<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](https://docs.fabrick.com/en/payment-hub-and-orchestra/ecommerce/alternative-payments/apple-pay/#additional-configuration-for-web-component-and-lightbox) must be completed.

```html
<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"`

`button-style="white"`

Example with Italian localisation:

![Apple Pay button with Italian localisation](https://docs.fabrick.com/en/assets/images/fbk-apple-pay-italian-locale-f3cc4c4db7b3fff35efd91d6ae08dbd1.png)

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](https://docs.fabrick.com/en/assets/images/applepay-02-21cca24dcb502f83f4cb71264c73adae.png)

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](https://docs.fabrick.com/en/assets/images/applepay-03-5538cf4dfb27ef8899632b0cad7bb267.png)

---

### `<fbk-google-pay>`

Shows a standalone Google Pay button.

> **Configuration required**
>
> To show the button, the [Google Pay configuration for Web Components](https://docs.fabrick.com/en/payment-hub-and-orchestra/ecommerce/alternative-payments/google-pay/#additional-configuration-for-web-component-and-webview) must be completed.

```html
<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"`

`button-style="white"`

---

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

- [Apple Pay — Additional configuration for Web Component and Lightbox](https://docs.fabrick.com/en/payment-hub-and-orchestra/ecommerce/alternative-payments/apple-pay/#additional-configuration-for-web-component-and-lightbox)
- [Google Pay — Additional configuration for Web Component and WebView](https://docs.fabrick.com/en/payment-hub-and-orchestra/ecommerce/alternative-payments/google-pay/#additional-configuration-for-web-component-and-webview)

---

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

```json
{
  "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:

```js
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](https://docs.fabrick.com/en/payment-hub-and-orchestra/ecommerce/integration-methods/web-component/#apple-pay-and-google-pay)).