Web

Overview

📘

Version 1.0 and later

Version 1.0 of the SDK introduces breaking changes that require changes in your application code if you had previously integrated an early version.

Documentation for older versions of the iOS SDK can be found here.

The Knot Link SDK provides a seamless way for end users to link their merchant accounts to your web app, serving as the foundation for Knot's merchant connectivity platform. It is a client-side integration, consisting of initializing & configuring the SDK and handling events.

Installation

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

The next tag is applied in version 1.0.0+, which is not automatically fetched by npm when running npm install knotapi-js.

Via npm

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

npm install knotapi-js@next --save

Via CDN

For browser-based projects, use the KnotapiJS SDK via a CDN like below:

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

Initialization

Your backend will create a session by calling Create Session and provide it to your frontend. To start a Knot session, you must first configure the SDK. The configuration allows you to set the environment, product type, entry point, and other user experience configurations.

Configure the SDK

The SDK is configured using the following parameters when using the open method:

🚧

TransactionLink

Please note that passing a single value in merchantIds is required when product = transaction_link.

Open the SDK

Invoke the open method with the parameters like below:

Node.js

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

// Invoke the open method with parameters
knotapi.open({
sessionId: "Your Session ID",
clientId: "Your Client ID",
environment: "development",  // or "production"
product: "card_switcher",  // or "transaction_link"
merchantIds: [17],
entryPoint: "onboarding"
});

Browser

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

// Invoke the open method with parameters
knotapi.open({
sessionId: "Your Session ID",
clientId: "Your Client ID",
environment: "development",  // or "production"
product: "card_switcher",  // or "transaction_link"
merchantIds: [17],
entryPoint: "onboarding"
});

Single Merchant Flow

If you decide to use List Merchants to retrieve a list of merchants, list them in your app, and then open the SDK with a single merchant, you can do so by passing a merchant ID when initializing the SDK. More in Retrieving & Listing Merchants. The merchant ID is the same across all environments.

Although available, 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.

Entry Points

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 when initializing the SDK. This value will be returned in the AUTHENTICATED webhook.

Categories & Search

Users are presented with a list of merchants in the SDK (unless you provide a single merchant as described above). Accompanying the list is a set of categories and a search experience. Each of these components is visible to users by default (as set in Knot's backend).

You can choose to remove either of them by setting useCategories: false and useSearch: false when initializing the SDK. This is not recommended.

Events

The open method provides several callbacks you can use to receive events from the SDK.

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

onSuccess

This event is called when a user successfully logged in to the merchant and their card was switched. It takes the following arguments: product and details, the latter of which contains the merchantName field, representing the merchant for which the card was updated.

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

onError

This event is called when an error occurs during SDK initialization. It takes the following arguments: product, errorCode, and message.

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

onExit

This event is called when a user closes the SDK.

onEvent

This event is called when certain events occur in the SDK. With this callback, you will be able to understand how a user is progressing through their lifecycle of authenticating to a merchant. It takes the following arguments: product, event, merchant, payloadand taskId.

  onEvent: (product, event, merchant, payload, taskId) => {
    console.log("onEvent", product, event, merchant, payload, taskId);
}