Fidel.ukFidel - Home

Web SDK v3 v2Improve 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 Fidel Mobile 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. Please contact us at devrel@fidel.uk if you experience any browser-related issues.

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

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

Fidel.openForm({
    companyName: "Fidel",
    sdkKey: "pk_test_demo",
    programId: "bca59bd9-171b-4d1f-92af-4b2b7305268a",
    callback() {
        console.log(arguments);
    },
});

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.

Fidel.openForm({
    companyName: "Fidel",
    sdkKey: "pk_test_demo",
    programId: "bca59bd9-171b-4d1f-92af-4b2b7305268a",
    callback() {
        console.log(arguments);
    },
    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

companyNamerequired
the name of the company using card-linking
sdkKeyrequired
a valid SDK Key. You can find yours in the Fidel Dashboard. It starts with `pk_`.
programIdrequired
the id of the Fidel Program to link the card to.
callback
callback function to be called when the form is submitted
countriesArray with possible values: GBR, IRL, USA, SWE
when the array has only one entry, that is set as the country of issue for all Cards collected and the country select box is removed from the UI. If the array has multiple entries, those are the only ones available in the country select box.
metadata
name of the global metadata object
closeOnSuccessdefault: true
toggles the web form auto-close behaviour on successful card linking
schemesobject with boolean properties for mastercard, visa and amex. By default, all three are true.
toggles the availability of the Mastercard, Visa and Amex card schemes in the form
custom
object that allows you to customize the UI for the Web SDK. You can find the structure for it in the customization section below.

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:

<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: "pk_test_demo",
    programId: "bca59bd9-171b-4d1f-92af-4b2b7305268a",
    callback() {
      console.log(arguments);
    },
  });
});
</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

<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: "pk_test_demo",
    programId: "bca59bd9-171b-4d1f-92af-4b2b7305268a",
    callback() {
      console.log(arguments);
    },
    metadata: {
        id: 'this-is-the-metadata-id',
        myUserId: '123',
        customKey: 'customValue'
    }
  });
});
</script>

Customizing the Fidel 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 paramets, all of which are optional.

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