KnotapiJS SDK Documentation

Introduction

KnotAPI for Web is an embeddable framework that is bundled and distributed with your application 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 user

Next, create a user and obtain the knot_access_token. We recommend, saving this knot_access_token for future debugging, logging, and connecting.

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 interaction 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, payload, taskId) => { console.log("onEvent", event, merchant, payload, taskId); },
});

Callbacks

The openCardOnFileSwitcher method supports several callbacks to handle various events:

• onSuccess: This callback is triggered when the card update process completes successfully. It receives a single object argument containing details about the event.

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

The details object contains the following fields:

| Field | Type | Description | |--------------|----------|-------------------------------------------------------------------------------------| | merchantName | string | The name of the merchant for which the card was updated. | | cardId | string | The unique identifier provided for the card when calling openCardOnFileSwitcher. |

• onError: This callback is triggered when an error occurs during the card update process. It receives two arguments: errorCode, a string indicating the type of the error, and message, a string providing additional details about the error.

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

• onEvent: This callback is triggered when certain events in the Card switcher flow have occurred. It receives two arguments: event, a string representing the event name, and details, an object containing information about the event.

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

Event Details

The event string can be one of the following:

| Event | Description | Payload | |---------------------|-------------------------------------------------------------------------------------------------------------------------|----------------------------------------| | MERCHANT_OPENED | Triggered when the user open the merchant login page to enter credentials. | {merchant: string // merchant name}\ | | LOGIN_STARTED | Triggered when the Card switcher starts logging into an account. | {merchant: string // merchant name} | | CREDENTIALS_SUCCESS | Triggered when the Card switcher successfully logs into an account. | {merchant: string // merchant name} | | CREDENTIALS_FAILED | Triggered when the Card switcher fails to log into an account. | {merchant: string // merchant name} | | OTP_REQUIRED | Triggered when the Card switcher requires the user to enter an OTP. (only for some merchants) | {merchant: string // merchant name} | | QUESTIONS_REQUIRED | Triggered when the Card switcher requires the user to answer one or more security question. (only for some merchants) | {merchant: string // merchant name} | | APPROVAL_REQUIRED | Triggered when the Card switcher requires the user to approve the login in the merchant app. (only for some merchants) | {merchant: string // merchant name} | | CLOSE | Triggered when the card update process is cancelled by the user. | {merchant: string // merchant name} |

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

| Field | Type | Description | |--------------|----------|-----------------------------------------------------| | merchantName | string | The name of the merchant related to the event. | | errorCode | string | The error code associated with an error event. | | message | string | The error message associated with an error event. |

| ErrorCode | Description | Message | |----------------------|---------------------------------------------------------------------|-----------------------| | WRONG_CREDENTIALS | The credentials provided are incorrect. | Wrong credentials | | OTP_FAILED | Not received The OTP was not received by the user. | Verification required | | | CARD_FAILED | An error related to the card info occurred when updating the card. | Card not added | | NO_SUBSCRIPTION | The user does not have a subscription with the merchant. | Card not added | | ACCOUNT_ISSUE | There is an issue with the user's account. | Card not added | | MERCHANT_DOWN | The merchant's service is currently unavailable. | Card not added | | COF_IS_NOT_SUPPORTED | Card on file is not supported by the merchant. | Card not added | | OTHER | An 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: "cc144c8f-d248-43dc-9ac1-b82d4f5b6a97",
        clientId: '3f4acb6b-a8c9-47bc-820c-b0eaf24ee771',
        environment: "sandbox",
        primaryColor: "#000000",  // Button color
        textColor: "#ffffff",     // Button text color
        companyName: "Millions",  // Company name
        useCategories: false,     // Whether to use categories for merchant selection
        logo: "https://1000logos.net/wp-content/uploads/2017/05/emblem-Paypal-768x768.jpg",  // 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

The Development is one of the KnotAPI environments on which you can run your code, Sandbox 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

Production

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

Local

Prerequisites

Make sure you have the following installed on your machine:

1. Homebrew (if not already installed):

   • Install Homebrew by running the following command in your terminal:

     /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

2. Node.js and npm:

   • Install Node.js and npm using Homebrew:

     brew install node

Steps to Set Up and Run the Application

1. Navigate to the src/demo directory:

   cd src/demo

2. Install dependencies:

   npm install

3. Edit the homePage.tsx file to update the token:

   • Open src/demo/pages/homePage.tsx in your preferred editor.
   • Update the token for all Sandbox (Staging) environments. You can retrieve the token from 1Password using this link: 1Password Sandbox Token.
   • If the link does not work, ask Tarik for assistance.

   Note: This token should be moved to a .env file for better security practices. TODO: Move this token to .env in the future.

4. Install and run the KnotAPI project:

   • Clone and set up the KnotAPI project by following these steps:

     git clone https://github.com/millionscard/knotapi
     # ... follow steps from readme.md
     yarn install
     yarn start

   • Note the local URL with the port in the output, e.g., http://localhost:4201.

5. Update src/lib/index.ts with the local URL:

   • Open src/lib/index.ts and update lines 158 and 159 with your local URL (e.g., http://localhost:4201):

     const urls = {
         production: IS_STAGING ? 'https://inter-prod-switcher-knotapi.vercel.app/' : 'https://cardswitcher.knotapi.com/',
         sandbox: 'http://localhost:4201',
         development: 'http://localhost:4201',
     }

   • TODO: Implement and use via .env

6. Install project dependencies:

   • From the project root, install dependencies by running:

     yarn install

7. Run the project in watch mode:

   • Start the application with live reloading:

     yarn watch

Summary

After following these steps, your application should be running locally with the correct configuration for development. If you encounter any issues, feel free to ask for assistance.

Happy coding!