KnotAPI Web SDK

Overview

KnotAPI for Web is an embeddable framework that is bundled and distributed with your application and used to create an easy and accessible experience for your customers to update their old saved cards across the web to your new card.

Integration

Hosting of the JavaScript SDK

The KnotapiJS SDK is hosted on unpkg.com, a popular CDN for everything on npm. You can also host the SDK on your servers if preferred.

Installation

Via npm

For Node.js environments, use npm to install the KnotapiJS SDK:

npm install knotapi-js --save

Via CDN

For browser-based projects, you can use the KnotapiJS SDK via a CDN:

<script src="https://unpkg.com/knotapi-js"></script>

Usage

Create a session

Then, create a session and obtain the session ID. We recommend, saving this session ID for future debugging, logging, and connecting.

To start the process of updating a card, you need to call the openCardOnFileSwitcher method on the KnotapiJS instance. This method accepts an options object containing the session ID, client ID, and environment for the operation.

Node.js

In a Node.js environment, import KnotapiJS as follows:

import KnotapiJS from "knotapi-js";
const knotapi = new KnotapiJS();

// Invoke the openCardOnFileSwitcher method with required parameters
knotapi.openCardOnFileSwitcher({
 	 	sessionId: "Your Session ID",
  	clientId: "Your Client ID",
  	environment: "development"  // or "production"
});

Browser

In a browser environment, access KnotapiJS like this:

const KnotapiJS = window.KnotapiJS.default;
const knotapi = new KnotapiJS();

// Invoke the openCardOnFileSwitcher method with required parameters
knotapi.openCardOnFileSwitcher({
  	sessionId: "Your Session ID",
  	clientId: "Your Client ID",
  	environment: "development"  // or "production"
});

When you call openCardOnFileSwitcher, it opens our user interface in an iframe overlaid on your UI. The parameters you provide determine the details of this interface and the session in which the user will operate.

In this interface, the user can start the flow of updating their card. The UI guides the user through the necessary steps, handling all user interactions until the card update process is completed.

Remember to handle the various events and potential errors that can occur during this process by providing appropriate callback functions in the options object. You can find more information about these callbacks in the Callbacks section of this document.

JavaScript Callbacks

The openCardOnFileSwitcher method of KnotapiJS SDK provides several callbacks that you can use to handle different events.

knotapi.openCardOnFileSwitcher({
    sessionId: "Your Session ID",
  	companyName: "Your Company Name",
  	clientId: "Your Client ID",
  	environment: "development",  // or "production"
  	onSuccess: (details) => { console.log("onSuccess", details); },
  	onError: (errorCode, message) => { console.log("onError", errorCode, message); },
  	onEvent: (event, merchant) => { console.log("onEvent", event, merchant); },
});

Callbacks

  • onSuccess: This callback is triggered when the card update process completes successfully.

The callback payload object contains the following fields:

FieldTypeDescription
merchantNamestringThe name of the merchant for which the card was updated.
cardIdstringThe unique identifier provided for the card when calling openCardOnFileSwitcher.
onSuccess: (details) => {
  console.log("onSuccess", details);
}
  • onError: This callback is triggered when an error occurs during the card update process.
FieldTypeDescription
errorCodestringThe error code associated with the error event.
messagestringThe error message associated with the error event.
  onError: (errorCode, message) => {
    console.log("onError", errorCode, message);
}
  • onEvent: This callback is triggered when certain events in the Card switcher flow have occurred.
FieldTypeDescription
eventstringThe event name.
detailsobjectThe details associated with the event.
  onEvent: (event, details) => {
    console.log("onEvent", event, details);
}

Event Details

When the onEvent callback is triggered, the details object will include event fields. The event can be one of the following:

EventDescriptionDetails
MERCHANT_OPENEDTriggered when the user open the merchant login page to enter credentials. {merchant: string // merchant name}
LOGIN_STARTEDTriggered when the Card switcher starts logging into an account. {merchant: string // merchant name}
CREDENTIALS_SUCCESSTriggered when the Card switcher successfully logs into an account. {merchant: string // merchant name}
CREDENTIALS_FAILEDTriggered when the Card switcher fails to log into an account. {merchant: string // merchant name}
OTP_REQUIREDTriggered when the Card switcher requires the user to enter an OTP. (only for some merchants) {merchant: string // merchant name}
QUESTIONS_REQUIREDTriggered when the Card switcher requires the user to answer one or more security question. (only for some merchants) {merchant: string // merchant name}
APPROVAL_REQUIREDTriggered when the Card switcher requires the user to approve the login in the merchant app. (only for some merchants) {merchant: string // merchant name}
CLOSEDTriggered when the card update process is cancelled by the user. {merchant: string // merchant name}

Error Details

When the onError callback is triggered, the details object will include errorCode and message fields providing details about the error. The errorCode can be one of the following:

CodeDescriptionMessage
WRONG_CREDENTIALSThe credentials provided are incorrect.Wrong credentials
OTP_FAILEDNot received The OTP was not received by the user.Verification required
CARD_FAILEDAn error related to the card info occurred when updating the card.Card not added
NO_SUBSCRIPTIONThe user does not have a subscription with the merchant.Card not added
ACCOUNT_ISSUEThere is an issue with the user's account.Card not added
MERCHANT_DOWNThe merchant's service is currently unavailable.Card not added
COF_IS_NOT_SUPPORTEDCard on file is not supported by the merchant.Card not added
OTHERAn unknown error occurred.Card not added

Card External Identifier

The Card External Identifier is a unique identifier that you can provide when invoking the openCardOnFileSwitcher function. This identifier can be used to associate the card update process with a specific card record in your system.

Here's an example of how you can include the Card External Identifier:

knotapi.openCardOnFileSwitcher({
    sessionId: "Your Session ID",
    clientId: "Your Client ID",
    environment: "development", // or "production"
    cardId: "Your Card External Identifier"
});

Open with Specific Merchants

In some cases, you might want to limit the card updating process to specific merchants. The KnotAPI.js SDK provides two options for this: merchantIds and merchantNames.

Here's an example of how to use these options:

knotapi.openCardOnFileSwitcher({
    sessionId: "Your Session ID",
    clientId: "Your Client ID",
    environment: "development", // or "production"
    merchantIds: [44, 16], // replace with your merchant IDs
    merchantNames: ["Netflix", "Amazon"] // replace with your merchant names
});

In this example, replace [44, 16] with an array of your merchant IDs and replace ["Netflix", "Amazon"] with an array of your merchant names.

  • merchantIds: This is an array of merchant IDs. Only the merchants with these IDs will be included in the card updating process.

  • merchantNames: This is an array of merchant names. Only the merchants with these names will be included in the card updating process.

Note: You can use either merchantIds or merchantNames or both. If both are provided, only the merchants that match both the IDs and the names will be included.

Customizing the UI

KnotAPI-JS provides several options to customize the look and feel of its user interface to align with your application. You can specify these options when calling openCardOnFileSwitcher.

Here is an example that shows all the possible customization options:

knotapiInstance.openCardOnFileSwitcher({
		sessionId: "Your Session ID",
    clientId: 'Your Client ID',
    environment: "development", // or "production"
    primaryColor: "#000000", // Button color
    textColor: "#ffffff", // Button text color
    companyName: "Company", // Company name
    useCategories: false, // Whether to use categories for merchant selection
    logo: "logo_url", // URL of the company logo
    useSelection: true, // Whether to enable merchant selection
    useSearch: false, // Whether to enable merchant search
});

Customization Options

You can customize the appearance and behavior of the SDK's user interface by setting the following options when calling openCardOnFileSwitcher:

  • primaryColor: (String) The color of the button in the UI. Should be a valid CSS color string.
  • textColor: (String) The color of the button text in the UI. Should be a valid CSS color string.
  • companyName: (String) The name of your company. This will be displayed in the UI.
  • useCategories: (Boolean) If set to true, merchants are displayed in categories. If false, merchants are displayed in a simple list.
  • logo: (String) The URL of your company's logo. This will be displayed in the UI.
  • useSelection: (Boolean) If set to true, users can select the merchant for which they want to update the card. If false, the selection of merchants is disabled.
  • useSearch: (Boolean) If set to true, users can search for merchants by name.

Environment

Development

Development is one of the KnotAPI environments on which you can run your code, Development is a test environment in which no real data can be used.

πŸ“˜

Test Credentials

To test a merchant you can use the login:

username/email: user_good
password: pass_good

Completing the switch

Before showing success in the SDK, Knot expects to receive card details. On the server side, listen for theAUTHENTICATED webhook before sending the card. You can enter your webhook on the dashboard here. Alternatively, in development only, you can mock the endpoint without using a webhook.

Production

Production is one of the KnotAPI environments on which you can run your code, While Development is intended as test environments, Production is intended for production code. It uses real world data


What’s Next