Quickstart

Get started with the CardSwitcher integration to provision cards to merchant accounts.

Introduction

Integrating Knot is quite simple. You’ll need a basic client-side and server-side integration: your backend creates a session, your client invokes the SDK, and once the user authenticates, your backend listens for the webhook and switches the card.

Set Up

1. Access your customer dashboard

   Ensure you have access to your Customer Dashboard and retrieve your client_id and secret, which you will use as the basic auth username and password for your API key respectively. Note that your client_id and secret vary between the development and production environments.

2. Install the SDK

   Install and import an SDK for your platform: iOS, Android, React Native, Flutter, or Web.

3. Subscribe to webhooks

   Register a webhook endpoint in the Customer Dashboard and subscribe to the webhook events your backend needs to be notified of when to send the card details to Knot and further card switching lifecycle events.

Start the Flow

1. Call the API to create a session

   With your client_id and secret for the development environment, call Create Session with type: card_switcher to create a session used when invoking the SDK.

   You can send the user’s email and phone_number when creating the session to automatically detect their online merchant accounts and personalize the experience in the SDK. See more here.

2. Initialize the SDK and handle callbacks

   Initialize the SDK with the session_id retrieved from Create Session. The SDK is where users will interact with the Knot UI to authenticate to various merchants. All login flows, including step-up authentication, are handled with the SDK. Users will see real-time feedback as they progress through authenticating with a merchant.

   Wire up onSuccess, onError, onExit, and onEvent to react to client-side events as the user moves through the flow. See further details on callback events for iOS, Android, React Native, Flutter, and Web.

   Tag your entry points. To provide better visibility into conversion across different entry points, the Knot SDK supports an entryPoint parameter when invoking the SDK. This value is returned in the down-funnel AUTHENTICATED webhook event, allowing you to measure conversion by entry point in your analytics tool of choice.

   Pass a distinct entryPoint value for each entry point location where the Knot SDK is invoked in your app. Common examples: onboarding, home, push-notif-X, in-app-lifecycle-card-X.

   Tagging entry points is strongly recommended to future-proof visibility into your implementation and allow for downstream conversion optimizations.

3. Switch a card

   Send card information to Switch Card or Switch Card (JWE) within 15 seconds of receiving the AUTHENTICATED webhook when send_card: true. This event is fired after a user authenticates to a merchant account. You can read more about sending card data to Knot here.

   In the development environment, you can bypass the client-side SDK entirely to test this flow. Use the Link Account endpoint with card_switcher: true to simulate a user authentication and fire the AUTHENTICATED webhook. See the testing guide for more detailed steps & instructions.

Testing

Validate your integration end-to-end in the development environment with the testing guide.

What’s Next

Personalization

Auto-detect a user’s online merchant accounts for a personalized card switching experience.

Subscription data

Receive subscription details back when a card is provisioned to a merchant account.

Detected accounts

Sync detected merchant accounts to power lifecycle and re-engagement campaigns.

Transaction data

Retrieve users’ SKU-level transaction history from their connected merchant accounts.