Web SDK v2 v3Improve this page

The Fidel SDKs provide a secure way for you to add card-linking capabilities to your applications. The alternative involves using the Fidel Cards API, but you'll need to be PCI Compliant before you can use it. Using the Fidel SDKs, card details are sent directly to the Fidel API through a secure connection without exposing your servers to sensitive information. They take care of all PCI Compliance requirements, so you don't have to.

The Fidel Web SDK v3 is a JavaScript-based SDK that injects a secure HTML iframe into your web page. Your users will need to have JavaScript enabled in their browsers.

The SDK provides a pre-built UI that allows you to easily collect credit card details, tokenise and link credit/debit cards with rewards services from your website, e-commerce platform or mobile web apps. However, for mobile apps, we recommend using the iOS, Android or React Native SDKs.

You can customize the UI of the SDK to match your use case. All modern desktop and mobile browsers are supported, including Chrome, Firefox, Safari, Microsoft IE11 and Edge.

After successfully tokenising and linking a card on the Visa, Mastercard or American Express networks, the Fidel API returns the created Card object. The Card object has a unique id that you can use to link each unique card and transaction to your user's account. The id of each linked card is present on the Transaction object as well, as cardId. You can create card-linked web and mobile applications with online and offline transaction data visibility in a matter of minutes.

Integrating the Web SDK

Integrating the Fidel Web SDK into your web application starts with loading the JavaScript file we provide, https://resources.fidel.uk/sdk/js/v3/fidel.js, in a <script> tag. It registers a global Fidel variable, and uses an options object to allow you to configure it when calling Fidel.openForm().

index.html
123456
<script
  type="text/javascript"
  src="https://resources.fidel.uk/sdk/js/v3/fidel.js"
  data-id="fidel-sdk"
></script>

Fidel Web SDK Configuration

You can configure the Fidel Web SDK by defining parameters when calling Fidel.openForm(). sdkKey, programId and companyName are the required parameters.

Important note: For security reasons, please DO NOT store the SDK Key in your codebase. Follow our SDK security guide for detailed recommendations.

1234567891011121314151617
Fidel.openForm({
  companyName: "Fidel",
  sdkKey: yourSdkKey,
  programId: "bca59bd9-171b-4d1f-92af-4b2b7305268a",
  onCardEnrolledCallback() {
    console.log("onCardEnrolledCallback called");
    console.log(arguments);
  },
  onCardEnrollFailedCallback() {
    console.log("onCardEnrollFailedCallback called");
    console.log(arguments);
  },
  onUserCancelledCallback() {
    console.log("onUserCancelledCallback called");
  },
});

The Fidel Web SDK can be customized to better fit your website. The functionality is customizable with the language, schemes, countries and closeOnSuccess parameters. There is also a versatile custom property, that accepts CSS styles and allows you to greatly customize the UI of the SDK.

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768
Fidel.openForm({
  companyName: "Fidel",
  sdkKey: yourSdkKey, // make sure to store it in a secure place
  programId: "bca59bd9-171b-4d1f-92af-4b2b7305268a",
  custom: {
    close: {
      location: "form",
    },
    overlay: {
      style: {
        background: "#111111",
      },
    },
    form: {
      style: {
        background: "#1C1C1C",
        border: "none",
      },
    },
    title: {
      style: {
        textAlign: "center",
        color: "white",
      },
    },
    cardNumber: {
      label,
      input,
    },
    expiryDate: {
      label,
      input,
    },
    country: {
      label,
      input,
    },
    submit: {
      style: {
        background: "#44EDB0",
        color: "#111111",
        borderRadius: "4px",
      },
    },
  },
});

const input = {
  style: {
    color: "#737373",
    border: "none",
    background: "#282828",
  },
  focusStyle: {
    background: "#303030",
    borderWidth: "2px",
    borderColor: "black",
  },
  errorStyle: {
    borderWidth: "2px",
    borderColor: "red",
  },
};

const label = {
  hide: true,
};

Fidel Web SDK Parameters

Fidel Web SDK Global Object

After adding the Web SDK script on your website, a global variable Fidel is created with two methods that you can use to open and close the web form manually, Fidel.openForm() and Fidel.closeForm().

To open the iframe overlay form with a button, you could use this example:

1234567891011121314151617181920212223242526272829
<button id="open-form" type="submit">Link Card</button>

<script
  type="text/javascript"
  data-id="fidel-sdk"
  src="https://resources.fidel.uk/sdk/js/v3/fidel.js"
></script>

<script type="text/javascript">
  document.getElementById("open-form").addEventListener("click", function () {
    Fidel.openForm({
      companyName: "Fidel",
      sdkKey: yourSdkKey, // make sure to store it in a secure place
      programId: "bca59bd9-171b-4d1f-92af-4b2b7305268a",
      onCardEnrolledCallback() {
        console.log("onCardEnrolledCallback called");
        console.log(arguments);
      },
      onCardEnrollFailedCallback() {
        console.log("onCardEnrollFailedCallback called");
        console.log(arguments);
      },
      onUserCancelledCallback() {
        console.log("onUserCancelledCallback called");
      },
    });
  });
</script>

Web SDK metadata

The metadata id property is a non-unique index, so you can set it to a custom UID (unique identifier). Later you can query the cards using the same metadata.id. You can use our "List Cards from Metadata ID" API Endpoint.

Hint: Adding user data in the metadata as key: value pairs can simplify reconciliation with your system. For example, adding 'myUserId':'123' will help you match the added card to your user with id 123.

index.html
12345678910111213141516171819202122232425262728293031323334
<button id="open-form" type="submit">Link Card</button>

<script
  type="text/javascript"
  data-id="fidel-sdk"
  src="https://resources.fidel.uk/sdk/js/v3/fidel.js"
></script>

<script type="text/javascript">
  document.getElementById("open-form").addEventListener("click", function () {
    Fidel.openForm({
      companyName: "Fidel",
      sdkKey: yourSdkKey, // make sure to store it in a secure place
      programId: "bca59bd9-171b-4d1f-92af-4b2b7305268a",
      onCardEnrolledCallback() {
        console.log("onCardEnrolledCallback called");
        console.log(arguments);
      },
      onCardEnrollFailedCallback() {
        console.log("onCardEnrollFailedCallback called");
        console.log(arguments);
      },
      onUserCancelledCallback() {
        console.log("onUserCancelledCallback called");
      },
      metadata: {
        id: "this-is-the-metadata-id",
        myUserId: "123",
        customKey: "customValue",
      },
    });
  });
</script>

Customizing the Web SDK

The custom property allows for customizing most of the Fidel Web SDK UI. It supports the same CSS properties as the HTML DOM Style Object. Here is a complete list of parameters, all of which are optional.

The LabelStyles type includes the following parameters:

The InputStyles type includes the following parameters:

The definition of the custom parameter:

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889
Fidel.openForm({
    ...
    custom: {
        logo: {
            url: string,
            style: CSSPropertiesObject,
        },
        form: {
            style: CSSPropertiesObject,
        },
        overlay: {
            style: CSSPropertiesObject,
        },
        close: {
            location: 'form' | 'overlay' | 'none',
            color: string | { form: string, overlay: string },
        },
        title: {
            text: string,
            style: CSSPropertiesObject,
        },
        cardNumber: {
            label: {
                style: CSSPropertiesObject,
                errorStyle: CSSPropertiesObject,
                focusStyle: CSSPropertiesObject,
                placeholderColor: string,
                hide: boolean
            },
            input: {
                style: CSSPropertiesObject,
                errorStyle: CSSPropertiesObject,
                focusStyle: CSSPropertiesObject,
                placeholderColor: string
            },
        },
        expiryDate: {
            label: {
                style: CSSPropertiesObject,
                errorStyle: CSSPropertiesObject,
                focusStyle: CSSPropertiesObject,
                placeholderColor: string,
                hide: boolean
            },
            input: {
                style: CSSPropertiesObject,
                errorStyle: CSSPropertiesObject,
                focusStyle: CSSPropertiesObject,
                placeholderColor: string
            },
        },
        country: {
            label: {
                style: CSSPropertiesObject,
                errorStyle: CSSPropertiesObject,
                focusStyle: CSSPropertiesObject,
                placeholderColor: string,
                hide: boolean
            },
            input: {
                style: CSSPropertiesObject,
                errorStyle: CSSPropertiesObject,
                focusStyle: CSSPropertiesObject,
                placeholderColor: string
            },
        },
        terms: {
            text: string,
            privacyUrl: string,
            termsUrl: string,
            deleteInstructions: string,
            checkbox: {
                style: CSSPropertiesObject,
                checkedStyle: CSSPropertiesObject,
                checkColor: string,
            },
        },
        submit: {
            style: CSSPropertiesObject,
            hoverStyle: CSSPropertiesObject,
            loadingStyle: CSSPropertiesObject,
            successStyle: CSSPropertiesObject,
            defaultText: string,
            loadingText: string,
            successText: string,
        },
    }
})

Here are some examples of what is achievable using the customization:

Card entity

This object is returned through the onCardEnrolledCallback when a card is successfully enrolled.

Error object

This object is returned whenever you receive an error callback.

Error codes