Web SDKImprove this page

The Fidel API SDKs provide a secure way for you to add card-linking capabilities to your applications. The alternative involves using the Cards API, but you'll need to be PCI Compliant before you can use it. Using the Fidel API SDKs, card details are sent directly to 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 API Web SDK 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, tokenize 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 Fidel API's iOS, Android, 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. Please contact us if you experience any browser-related issues.

Card Verification

After the card has been linked to the Fidel system, a user with access to the account statement of the card must provide a verification token to verify consent. To implement this verification, use the Verified Enrollment SDK. There are two verification flows possible, depending on the card: Microcharge and 3D Secure (3DS).

Microcharge

In this verification process Fidel API will charge the card for a nominal amount (USD$0.50-1.00), which will be refunded within 72 hours. The cardholder checks their card statement to identify the charged amount and types the exact amount in the verification screen.

Since the verification process is not instantaneous and may require the cardholder to exit the SDK, the SDK stores a token which represents their card object (not the card details themselves) on the device they used. This means that cardholders will need to use the same device or enter their card details again to complete the verification. This token is erased once the verification is completed.

The charges made to the enrolled card will be made in the currency of the country selected. If a cardholder selects “United States” as the country where the card was issued, the charge will be in USD. If the developer listed only one country in SDK options (e.g. Canada), the currency of that country will be used (e.g. CAD).

🚧

If you are using a non-live environment, the microcharge will have a fixed amount of $0.67 which you can use to verify a test card.

3D Secure (3DS)

In this verification process Fidel API will ask users for additional information of their card, namely the card's CCV/CVC and cardholder name.

After the user adds the additional information, there could be two outcomes: either the card does not need further verification, and thus it's verified right away, ending the flow; or a fingerprint process will happen on the background, where data about the user's device is sent over to the issuer of the card as an additional security measure. This process is hidden from end users.

When the fingerprint finishes, there could again be two outcomes: as before, if the card does not need further verification, it'll be verified right away, ending the flow; or a challenge may be needed, in which the user may need to interact with an external application from the issuer of the card or input a code received via SMS or email. This challenge screen is completely dependent on the issuer and we don't have control over it, nor it can be modified or changed in any way.

If the challenge is successful, the user will be presented with a success screen and the card will be verified. If, for whatever reason, the card couldn't be verified, the user will be presented with an error screen, urging them to try the verifying their card again.

Contrary to the Microcharge flow, the verification process on 3DS is synchronous, meaning that users that leave in the middle of the flow will have to begin the process from the start. This, on the other hand, means that the SDK does not store anything about the card object on the device used.

Integrating the Web SDK

Integrating the Fidel API 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().

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

Web SDK Configuration

You can configure the Fidel Web SDK by defining parameters when calling the desired method.

Fidel.openForm()

This method is used for linking cards in stream and select programs. For transaction-stream programs, it can also trigger the verification process of the card. This method allows:

• Linking a card in a select program.
• Linking a card in a streamprogram, if the cardholder does not have access to the bank statement.
• Linking and verifying a card in a streamprogram, if the cardholder has access to the bank statement.

Configuration

There are also additional parameters that can improve your SDK experience.

Example

123456789101112131415161718192021222324252627282930
Fidel.openForm({
  companyName: "Fidel",
  sdkKey: yourSdkKey, // make sure to store it securely
  programId: "bca59bd9-171b-4d1f-92af-4b2b7305268a",
  programType: "transaction-stream",
  onCardEnrolledCallback() {
    console.log("onCardEnrolledCallback called");
    console.log(arguments);
  },
  onCardVerificationStartedCallback() {
    console.log("onCardVerificationStartedCallback called");
    console.log(arguments);
  },
  onCardEnrollFailedCallback() {
    console.log("onCardEnrollFailedCallback called");
    console.log(arguments);
  },
  onCardVerifiedCallback() {
    console.log("onCardVerifiedCallback called");
    console.log(arguments);
  },
  onCardVerifyFailedCallback() {
    console.log("onCardVerifyFailedCallback called");
    console.log(arguments);
  },
  onUserCancelledCallback() {
    console.log("onUserCancelledCallback called");
  },
});

If thirdPartyVerification.isChoiceAvailableis set to true, this screen appears, allowing the cardholder to choose between verifying the card on the spot or delegating the verification.

Fidel.verifyCard()

This method is used to resume the verification of a card that was previously linked but not verified.

Configuration

There are also additional parameters that can improve your SDK experience.

Example

12345678910
Fidel.verifyCard({
 sdkKey: yourSdkKey, // make sure to store it securely
 programId: "bca59bd9-171b-4d1f-92af-4b2b7305268a",
 cardToVerify: {
    id: "bf98f881-53fc-45ab-8788-5c63915b9cf2",
    consentId:"a9e5c141-4f61-428f-aedd-2248e6767dd7",
    last4Digits: "4011”
 }
});

Customization

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.

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869
Fidel.openForm({
  companyName: "Fidel",
  sdkKey: yourSdkKey, // make sure to store it securely
  programId: "bca59bd9-171b-4d1f-92af-4b2b7305268a",
  programType: "transaction-stream",
  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,
};

Web SDK Global Object

After adding the Web SDK script to 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(), Fidel.verifyCard() and Fidel.closeForm().
To open the iframe overlay form with a button, you could use this example:

123456789101112131415161718192021222324252627282930313233343536373839404142
<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 securely
      programId: "bca59bd9-171b-4d1f-92af-4b2b7305268a",
      programType: "transaction-stream",
      onCardEnrolledCallback() {
        console.log("onCardEnrolledCallback called");
        console.log(arguments);
      },
      onCardVerificationStartedCallback() {
        console.log("onCardVerificationStartedCallback called");
        console.log(arguments);
      },
      onCardEnrollFailedCallback() {
        console.log("onCardEnrollFailedCallback called");
        console.log(arguments);
      },
      onCardVerifiedCallback() {
        console.log("onCardVerifiedCallback called");
        console.log(arguments);
      },
      onCardVerifyFailedCallback() {
        console.log("onCardVerifyFailedCallback 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.

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

Customizing the Web SDK

Additional properties

Custom UI

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 is an example of what is achievable using the customization:

Card entity

Error object

Error codes