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

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

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071
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

ParameterValueDescription
companyName requiredstringThe name of the company using card linking.
sdkKey requiredstringA valid SDK Key. You can find yours on the Dashboard. It starts with "pk_".
programId requiredstringThe id of the Fidel API Program to link the card to.
programNamestringThe name of the Fidel API Program to link the card to.
callbackfunctionFunction to be called when the form is submitted.
containerHTML elementA wrapper element that you can wrap around the iframe.
countriesarray of strings
Possible values: 'GBR', 'IRL', 'USA', 'SWE'
If the array has only one value, that will be set as the country of issue for all collected cards and the country select box is removed from the UI.
If the array has multiple values, those will be the available options in the country select box.
languagestring
Possible values: 'EN', 'EN-BG', 'FR', 'JA', 'SV'
Default value: 'EN'
The language to be displayed. It follows `window.navigator.language` language codes.
metadataRecord<string, any>The global metadata object. See more details in the next sections.
closeOnSuccessboolean
Default value: true
Toggles the form's auto-close behavior on successful card linking.
schemes.mastercard
schemes.visa
schemes.amex
boolean
By default, all three are true.
Properties that toggle the availability of the Mastercard, Visa and Amex card schemes in the form.
customobjectObject 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:

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

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

ParameterValueDescription
logo.urlstringThe URL of the logo on the iframe.
logo.styleCSS propertiesThe style of the logo on the iframe.
form.styleCSS propertiesThe style of the form element of the iframe.
overlay.styleCSS propertiesThe style of the overlay element of the iframe.
close.locationstring
Possible values: form | overlay | none
Default value: overlay
The location of the close icon.
close.colorstringThe color of the close icon.
title.textstring
Default value: "Connect your card"
The text of the title at the top of the page.
title.styleCSS propertiesThe style of the title at the top of the page.
cardNumber.labelLabelStyles (see definition below)The style of the Card Number label.
cardNumber.inputInputStyle (see definition below)The style of the Card Number input field.
expiryDate.labelLabelStyles (see definition below)The style of the Expiry Date label.
expiryDate.inputInputStyle (see definition below)The style of the Expiry Date input field.
country.labelLabelStyles (see definition below)The style of the Country field label.
country.inputInputStyle (see definition below)The style of the Country input field.
terms.textstring
Default value: "I authorize {{scheme}} to monitor my payment card to identify transactions that qualify for a reward and for {{scheme}} to share such information with {{companyName}}, to enable my card linked offers and target offers that may be of interest to me."
The Terms of Use text.
terms.privacyUrlstringThe Privacy Policy URL.
terms.termsUrlstringThe Terms and Conditions URL.
terms.deleteInstructionsstring
Default value: "going to your account settings"
Text to inform the user about how to opt out from the transaction monitoring. It is appended to the text "You may opt out of transaction monitoring on the payment card you entered at any time by".
terms.checkboxstyle: CSS properties
checkedStyle: CSS properties
The styles of the terms checkbox.
terms.checkbox.checkColorstringThe border color of the terms checkbox.
submitstyle: CSS properties
hoverStyle: CSS properties
loadingStyle: CSS properties
successStyle: CSS properties
defaultText: string
Default value: "Continue" | "Verify", depending on the step
loadingText: string
successText: string
Parameters to customize the CTA button on the screens of the card verification.

The LabelStyles type includes the following parameters:

ParameterTypeDescription
label.hideCSS propertiesThe default style of the input
label.styleCSS propertiesThe style of the input
label.errorStyleCSS propertiesThe error style of the input
label.focusStyleCSS propertiesThe focus style of the input
label.placeholderColorstringThe color of the input's placeholder

The InputStyles type includes the following parameters:

ParameterTypeDescription
input.styleCSS propertiesThe default style of the input
input.errorStyleCSS propertiesThe error style of the input
input.focusStyleCSS propertiesThe focus style of the input
input.placeholderColorstringThe color of the input's placeholder

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: