React Native

KnotAPI React Native SDK

Reference for integrating with the KnotAPI Card Switcher React Native SDK


KnotAPI for React Native 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.

Install React Native SDK

In your react-native project directory:

npm install react-native-knotapi --save
yarn add react-native-knotapi

Automatic installation

From React Native 0.60 and higher, linking is automatic.

Manual installation

You need to run:

react-native link react-native-knotapi

Import SDK

To open the Card on File Switcher first you must import the SDK

Import knotapi

import { openCardOnFileSwitcher, addCardSwitcherListener, eventNames } from "react-native-knotapi";

Create a session

Then, create a session and obtain the session ID. We recommend, saving this session ID for future debugging, logging, and connecting.

Open Card On File Switcher

To open the Card on File Switcher, you can use the following:

  sessionId: SESSION_ID,
  clientId: CLIENT_ID,
  customization: {
    companyName: COMPANY_NAME
  environment: "development",
  entryPoint: "onBoarding"

The entry point parameter in the openCardOnFileSwitcher function is designed to provide detailed analytics on user interactions with the card switcher in your app. By specifying where in the SDK the function is invoked, you gain valuable insights into user behavior and preferences. This data is essential for understanding how different sections of your app contribute to the overall user experience.

Open with specific merchants

To open the Card on File Switcher with specific merchants, first contact [email protected] to receive the list of merchantIds and names. Pass in the ids or merchant names in the session instance as an array of numbers or strings.

  sessionId: SESSION_ID, clientId: CLIENT_ID, merchantIds: [44, 16], merchantNames: ["Amazon"], environment: "development"



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

Completing the switch

Before showing success in the SDK, Knot expects to receive card details. On the server side, listen for theAUTHENTICATED webhook before sending the card. You can enter your webhook on the dashboard here. Alternatively, in development only, you can mock the endpoint without using a webhook.


The event is called when a user successfully updates their payment info in a merchant account. It takes a single argument, containing the Merchant name String .

let listener = addCardSwitcherListener(eventNames.onSuccess, merchant => {


This event is called when an error occurs during SDK initialization or when an update to a payment method in a merchant account is unsuccessful. It takes two String arguments errorCode and errorMessage.

let listener = addCardSwitcherListener(eventNames.onError, (errorCode, errorMessage) => {
  console.log(`Error ${errorCode}: ${errorMessage}`);


This event is called when a user closes the SDK.

let listener = addCardSwitcherListener(eventNames.onExit, () => {


This event is called when certain events in the CardSwitcher flow have occurred, for example, when the user start updating payment info of an account. This enables your application to gain further insight into what is going on as the user goes through the Account Updater flow. It should take a two String arguments eventName and merchantName.

let listener = addCardSwitcherListener(eventNames.onEvent, event => {
refresh session request

When the session used to initialize the SDK needs to be refreshed.

login started

When the Account Updater starts login in an account.

login success

When the Account Updater successfully login in an account.

require otp

When the Account Updater requires the user to enter an OTP.

card error

When the Account Updater encounters an error related the card info when updating the card.