Web
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.
Expected behavior
It's expected that your integration with Knot will retrieve and pass a new
session_id
into the SDK on each initialization.
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.
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 in the session instance as an array of numbers. More in Retrieving & Listing Merchants. The merchant ID is the same across all environments.
Single Merchant ID
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 (Not Recommended)
If multiple merchant IDs are provided, 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.
knotapi.openCardOnFileSwitcher({
sessionId: "Your Session ID",
clientId: "Your Client ID",
environment: "development", // or "production"
merchantIds: [44] // replace with your merchant IDs
});
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 setUseCategories: false
and setUseSearch: false
. This is not recommended.
knotapiInstance.openCardOnFileSwitcher({
sessionId: "Your Session ID",
clientId: 'Your Client ID',
environment: "development", // or "production"
setUseCategories: true, // Whether to use categories for merchant selection
setUseSearch: 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",
clientId: "Your Client ID",
environment: "development", // or "production"
onSuccess: (merchant) => { console.log("onSuccess", merchant); },
onError: (errorCode, message) => { console.log("onError", errorCode, message); },
onEvent: (event, merchant) => { console.log("onEvent", event, merchant); },
});
onSuccess
This event is called when a user successfully logged in to the merchant and their card was switched. It takes a single string argument containing the name of the merchant.
onSuccess: (merchant) => {
console.log("onSuccess", merchant);
}
onError
This event is called when an error occurs during SDK initialization or when a card switch is unsuccessful. It takes two string arguments containing the error code and message. A list of possible errors can be found here.
onError: (errorCode, errorMessage) => {
console.log("onError", errorCode, errorMessage);
}
onExit
This event is called when a user closes the SDK
onExit: () => {
console.log("onExit");
}
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. This event takes three string arguments containing the event name, merchant name, and task id.
onEvent: (event, merchant, taskId) => {
console.log("onEvent", event, merchant, taskId);
}
Events
When the onEvent
callback is triggered, the details object will include event
fields. The event
can be one of the following:
Event | Description |
---|---|
refresh session request | When the session used to initialize the SDK needs to be refreshed. |
merchant clicked | When a user clicks on a merchant from the merchant list. |
login started | When a user submits their credentials to login to the merchant. |
authenticated | When a user successfully logs in to the merchant. |
credentials failed | When a user is unsuccessful in logging in to the merchant. |
otp required | When a user needs to enter an OTP code to login to the merchant. |
questions required | When a user needs to enter the answers to security questions to login to the merchant. |
approval required | When a user needs to approve the login to the merchant typically by responding to a push notification or SMS from the merchant. |
Updated 12 days ago