React Native

Overview

Version 1.0+ of the React Native SDK introduces breaking changes that require changes in your application code if you had previously integrated an early version. See the Migration Guide for further details.

SDK Updates
New versions of the SDK are released frequently, not only to add new features and address issues in the SDK, but also to continuously improve the conversion of merchant login flows. As a result, it is strongly recommended that you frequently update your SDK version across any platforms where you invoke the SDK.

The Knot Link SDK provides a seamless way for end users to link their merchant accounts to your React Native 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 Knot SDK can be installed using npm or yarn in your react-native project directory, like below

npm install react-native-knotapi --save

From React Native 0.60 and higher, linking is automatic. If you need to manually install the SDK, run the below:

Shell

react-native link react-native-knotapi

Usage

Import methods like the below:

import {
  Knot,
  addKnotListener,
 } from "react-native-knotapi";

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 session with a KnotConfiguration class. The configuration allows you to set the environment, entry point, and other user experience configurations.

It’s expected that your integration with Knot will retrieve and pass a new session into the SDK on each initialization.

Configure the session

The KnotConfiguration and CustomerConfiguration classes are used to initialize the SDK with specific parameters.

`KnotConfiguration`

Name	Type	Description
sessionId	string	The session created by calling `/session/create` in your backend.
clientId	string	Your organization’s client ID. Note that this varies between `development` and `production` environments.
environment	string	The desired environment (`development` or `production`).
product	string	Optional. Ignored in version 1.0.7+ and fully deprecated in the next major version. The Knot product the session will inherit — the same as the type of session created (e.g. `card_switcher`, `transaction_link`).
entryPoint	string	Optional. The specific entry point from within your app where you are initializing the Knot SDK (e.g. `onboarding`).
useCategories	boolean	Optional. Whether to display merchant categories and therefore group merchants into categories for discoverability. Default: `true`.
useSearch	boolean	Optional. Whether to display the search bar, enabling users to search for merchants. Default: `true`.
merchantIds	number[]	Optional. A list of merchant ID(s) to display. It is recommended to provide 0 or 1 merchant ID depending on your desired user experience.
domainUrls	string[]	Optional. Android only. A set of domains for which Knot should explicitly not clear cookies.

`CustomerConfiguration`

This class is entirely optional and infrequently used, typically only when you offer Knot for multiple, differently-named card programs in the same app. The Knot team will set pre-defined values for each parameter that you can then subsequently pass into the SDK. Passing a value that is not pre-defined will result in an onError callback. To take advantage of this functionality, please contact the Knot team who will be happy to assist you.

Name	Type	Description
cardName	String	Optional. The differentiated display name for the card product, used inside the Knot SDK (e.g. `Debit Card`, `Credit Card`). This value will override the default value `Card`.
customerName	String	Optional. The differentiated display name for the company, used both as a standalone and prepended to the `cardName` (e.g. `Smart Bank`, `Payment Corp`). This value will override your default customer name value. Only recommended if you issue cards under multiple brands.
logoId	String	Optional. The differentiated logo for the company. This value will override your default logo.

See the following real example for how the parameters are used together in text inside the Knot SDK: "Your [customerName] [cardName | Card] was added."

 Knot.open({
      sessionId: 'session_12345', // Current session ID
      clientId: 'client_67890', // Your client ID
      environment: 'development', // 'development' || 'production'
      entryPoint: 'onboarding', // Defined by you
      useCategories: true, // Recommend true
      useSearch: true, // Recommend true
      merchantIds: [52], // Recommend 0 or 1 merchant IDs
      domainUrls: ["https://domain1.com", "https://domain2.com"], // Uncommon 
      customerConfig: { cardName: 'Card Name', customerName: 'Customer Name', logoId: 'LogoId' },
    });

Open the session

To begin the flow, use the open method like below:

 Knot.open({
      sessionId: 'session_12345', // Current session ID
      clientId: 'client_67890', // Your client ID
      environment: 'development', // 'development' || 'production'
      entryPoint: 'onboarding', // Defined by you
      useCategories: true, // Recommend true
      useSearch: true, // Recommend true
      merchantIds: [52], // Recommend 0 or 1 merchant IDs
      domainUrls: ["https://domain1.com", "https://domain2.com"], // Uncommon 
      customerConfig: { cardName: 'Card Name', customerName: 'Customer Name', logoId: 'LogoId' },
    });

To test logging in to a merchant in the SDK, please reference a set of available test credentials for the CardSwitcher product here and the TransactionLink product here.

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 configuring the session in the KnotConfiguration. 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 in when when configuring the session in the Knot.open. 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 in Knot.open. This is not recommended.

Events

To receive updates from the SDK, implement the addKnotListener method.

const onKnotSuccess = addKnotListener('knot:onSuccess', (event) => {
  console.log('onSuccess', 'event', event);
});

const onKnotEvent = addKnotListener('knot:onEvent', (event) => {
  console.log('onEvent', 'event', event);
});

const onKnotError = addKnotListener('knot:onError', (event) => {
  console.log('onError', 'event', event);
});

const onKnotExit = addKnotListener('knot:onExit', (event) => {
  console.log('onExit', 'event', event);
});

The provided Typescript types can be found below:

export type KnotError = {
  errorCode: string;
  errorDescription: string;
  product?: 'card_switcher' | 'transaction_link';
};

export type KnotEvent = {
  event: string;
  environment: string;
  product?: string;
  merchantName: string;
  merchantId?: string;
  metaData?: Record<string, unknown>;
  product?: 'card_switcher' | 'transaction_link' | 'link';
  taskId?: string;
};

export type KnotSuccess = {
  merchant: string;
  product?: 'card_switcher' | 'transaction_link' | 'link';
};

export type KnotExit = {
  product?: 'card_switcher' | 'transaction_link' | 'link';
} | void;

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

`onError`

This event is called when an error occurs during SDK initialization and emits a KnotError with the following errors:

errorCode	errorDescription
Invalid_Session	The session is invalid.
Expired_Session	The session has expired.
Invalid_Client_Id	The client ID is invalid.
Internal_Error	An internal error occurred.
Merchant_Id_Not_Found	The merchant ID is required.
Invalid_Card_Name	The card name is invalid.
Invalid_Customer_Name	The customer name is invalid.
Invalid_Logo_Id	The logo ID is invalid.

`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. The following list contains all possible events emitted in the KnotEvent.event property:

Name	Purpose
REFRESH_SESSION_REQUEST	Emitted when the session used to initialize the SDK needs to be refreshed.
MERCHANT_CLICKED	Emitted when a user clicks on a merchant from the merchant list.
LOGIN_STARTED	Emitted when a user submits their credentials to login to the merchant.
AUTHENTICATED	Emitted when a user successfully logs in to the merchant.
OTP_REQUIRED	Emitted when a user needs to enter an OTP code to login to the merchant.
SECURITY_QUESTIONS_REQUIRED	Emitted when a user needs to enter answers to security questions to login to the merchant.
APPROVAL_REQUIRED	Emitted when a user needs to approve the login - often via a push notification or directly in the merchant’s mobile app - to login to the merchant.
ZIPCODE_REQUIRED	Emitted when a user needs to enter their zip code to login to the merchant.
LICENSE_REQUIRED	Emitted when a user needs to enter their drivers license to login to the merchant.

Other Options

Close the SDK

If you need to explicitly close the SDK, use the below method, otherwise end users will naturally close the SDK as they interact with the interface.

JavaScript

Knot.close();

Maintain cookies

Android only.

Knot clears cookies for security purposes. If your app relies on cookies, you can allowlist specific domains using the domainUrls configuration in Knot.open. This is uncommon.

JavaScript

Knot.open({
  sessionId: 'session_12345', // Current session ID
  clientId: 'client_67890', // Your client ID
  environment: 'development', // 'development' || 'production'
  entryPoint: 'onboarding', // Defined by you
  useCategories: true, // Recommend true
  useSearch: true, // Recommend true
  merchantIds: [52], // Recommend 0 or 1 merchant IDs
  domainUrls: ["https://domain1.com", "https://domain2.com", .....],
  customerConfig: { cardName: 'Card Name', customerName: 'Customer Name', logoId: 'LogoId' },
})

General

SDK

CardSwitcher

TransactionLink

Shopping

Merchant Account Linking

React Native

Overview

Installation

Usage

Initialization

Configure the session

`KnotConfiguration`

`CustomerConfiguration`

Open the session

Single Merchant Flow

Entry Points

Categories & Search

Events

`onSuccess`

`onError`

`onExit`

`onEvent`

Other Options

Close the SDK

Maintain cookies

General

SDK

CardSwitcher

TransactionLink

Shopping

Merchant Account Linking

​Overview

​Installation

​Usage

​Initialization

​Configure the session

​KnotConfiguration

​CustomerConfiguration

​Open the session

​Single Merchant Flow

​Entry Points

​Categories & Search

​Events

​onSuccess

​onError

​onExit

​onEvent

​Other Options

​Close the SDK

​Maintain cookies

Overview

Installation

Usage

Initialization

Configure the session

`KnotConfiguration`

`CustomerConfiguration`

Open the session

Single Merchant Flow

Entry Points

Categories & Search

Events

`onSuccess`

`onError`

`onExit`

`onEvent`

Other Options

Close the SDK

Maintain cookies