Hosting the SDK

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

Installing the SDK

npm

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

npm install knotapi-js --save

CDN

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

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

Using the SDK

Create a Session

Then, Create a Session to retrieve a session_id. We recommend saving this session_id for future debugging and logging in development.

Open the SDK

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 the following:

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"
});

Remember to handle the various events and potential errors that can occur during this process by providing appropriate callback functions in the options object. More on callbacks below.

Switch a Card

After a user authenticates to a merchant, you will receive the AUTHENTICATED webhook indicating that it is time to switch the card. Immediately upon receiving this webhook, make a call to the Switch Card endpoint. Alternatively, you can use the login success onEvent callback to determine that it is time to switch the card.

Opening With Specific Merchants

If you decide to use Get Merchants to retrieve a list of merchants, list them in your app, and then open the SDK with a specific merchant, you can do so by passing a merchant ID or merchant name in the session instance as an array of numbers or strings. More in Retrieving & Listing Merchants.

Single Merchant ID or Name

If a single merchant ID or merchant name is provided, the user will be sent directly to that merchant's login experience in the SDK.

Multiple Merchant IDs or Names (Not Recommended)

If multiple merchant IDs or merchant names are provided, but not both, the user will see a list of only those merchants to select from. It is not recommended that you provide a long list of merchants in order to remove a few, but rather "hide" certain merchants that you desire from your Customer Dashboard.

Merchant IDs and Names Used Together (Not Recommended)

If a merchant ID and merchant name (or multiple) are provided, the user will see a list of only the merchants that match both the ID(s) and the name(s).

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
});

Opening With an Entry Point

In your app's user experience, you may choose to integrate Knot in one or multiple places (e.g. from different tabs or screens). How users behave when interacting with Knot from each of these "entry points" may vary and it will be useful for you to be able to differentiate these groups of users by entry point in order to assess the value of each entry point. You can provide a value for the entry point in the session instance when you open the SDK. This value will be returned in the AUTHENTICATED webhook.

knotapi.openCardOnFileSwitcher({
    sessionId: "Your Session ID",
    clientId: "Your Client ID",
    environment: "development", // or "production"
    entryPoint: "Onboarding", // the entry point in your app
});

Opening With Categories and Search

Users are presented with a list of merchants in the SDK (unless you provide a single merchant as described above. Along with the list is a set of categories and search experience. Each of these components is visible to users by default (as set in Knot's backend), however, you can choose to remove either of them by setting useCategories: false and useSearch: false. This is not recommended.

knotapiInstance.openCardOnFileSwitcher({
		sessionId: "Your Session ID",
    clientId: 'Your Client ID',
    environment: "development", // or "production"
    useCategories: true, // Whether to use categories for merchant selection
    useSearch: true, // Whether to enable merchant search
});

Testing in Development

To test a user's lifecycle through the SDK in the Development environment, you can use the following credentials when authenticating to a merchant:

username/email: user_good; password: pass_good

A full list of credentials useful in testing various merchant login scenarios can be found here.

Events

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: called when a user successfully updates their payment info in a merchant account.

The callback payload object contains the following fields:

onSuccess: (details) => {
  console.log("onSuccess", details);
}

• onError: called when an error occurs during SDK initialization or when an update to a payment method in a merchant account is unsuccessful.

  onError: (errorCode, message) => {
    console.log("onError", errorCode, message);
}

• onClose: This callback is triggered when the SDK is closed.

  onClose: () => {
    console.log("onClose");
}

• onEvent: This callback is triggered when certain events in the Card switcher flow have occurred.

  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:

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: