Quickstart

Introduction

Detect enables you to identify a user’s online merchant accounts and optionally retrieve them from the Knot platform, allowing you to then personalize your user experience.

Getting started

Email-Based in CardSwitcher

This option is for those who’ve already implemented the CardSwitcher product.

1. Update session creation

   When calling Create Session to create a session for the SDK, simply add the user’s email address and phone number to the request.

   curl --request POST \
     --url https://development.knotapi.com/session/create \
     --header 'Authorization: Basic <encoded-value>' \
     --header 'Content-Type: application/json' \
     --data '
   {
     "type": "card_switcher",
     "external_user_id": "123abc",
     "card_id": "81n9al10a0ayn13",
     "email": "[e-mail]",
     "phone_number": "[phone]"
   }
   '
   
2. Personalize the UX

   When the merchant selection experience is rendered in the SDK, it will be automatically personalized to take into account a user’s detected online merchant accounts

3. Optionally, receive detected merchant accounts

   Listen for the NEW_DETECTED_ACCOUNTS_AVAILABLE webhook event to be notified when new detected accounts have been found for a given user. The webhook payload includes a data.detected_accounts array with the user’s detected merchant accounts.

   To test receiving the NEW_DETECTED_ACCOUNTS_AVAILABLE webhook in the development environment, pass the user’s email into the email field when calling Create Session.

Email-Based Standalone

1. Access your dashboard

   Ensure you have access to the Knot Dashboard and retrieve your client_id and secret to create an API key. Learn more about creating an API key and authentication to the API here.

2. Call the API

   Call Detect Accounts with the user’s email and phone_number to detect their online merchant accounts.

3. Receive the webhook event

   Listen for the NEW_DETECTED_ACCOUNTS_AVAILABLE webhook event to be notified when new detected accounts have been found for a given user. The webhook payload includes a data.detected_accounts array with the user’s detected merchant accounts.

SSO

Start the flow

Access your dashboard

Ensure you have access to the Knot Dashboard and retrieve your client_id and secret to create an API key. Learn more about creating an API key and authentication to the API here.

Retrieve available merchants

Call List Merchants to retrieve a list of merchants that are available for merchant account detection by passing type = detect in the request. These are merchants you can allow users to link in your app and subsequently detect merchant accounts.

You will be notified via the MERCHANT_STATUS_UPDATE webhook when/if the available merchant list changes, even if temporarily.

Create a session

With your API key for the development environment, call Create Session with type: link to create a session used when invoking the SDK. More here on how to create an API key.

Install the SDK

Install an SDK of your choosing, for example on iOS here and android here.

Initialize the SDK

Initialize the SDK with the session_id retrieved from Create Session and a merchant Id retrieved from List Merchants in KnotConfiguration or you can use merchant_id: 60for Apple to get started quickly. 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 within the SDK. Users will see real-time feedback as they progress through authenticating with a merchant.

Link a merchant account

Login

In the development environment, login to a merchant account using user_good / pass_good credentials to link your user’s merchant account.

Handle webhook events

Subscribe to webhooks in the Knot Dashboard so your backend can be notified about user-generated, server-side events. Listen for the following events:

• AUTHENTICATED: fired when the authentication to a merchant is successful and the merchant account is therefore successfully linked to Knot. Similarly and as applicable, listen to the client-side onEvent callback in the SDK to receive the authenticated event.
• NEW_DETECTED_ACCOUNTS_AVAILABLE: fired when new detected accounts are available.

Search for detected accounts

When you receive the NEW_DETECTED_ACCOUNTS_AVAILABLE webhook, call Search Detected Accounts with a list of merchant or company names that are relevant to your use case. The endpoint will return whether a detected merchant account was found for the user at each one. This is useful when you have a specific set of merchants or companies you care about and want to know if a user has an account at any of them.

In the development environment, this endpoint accepts any list of names you provide and returns detected: true for 6 of them at random.

Receive detected accounts

The NEW_DETECTED_ACCOUNTS_AVAILABLE webhook payload includes a data.detected_accounts array with the user’s detected merchant accounts. The array includes only merchants that Knot supports on its platform (i.e. those with a merchant_id), making it useful for engaging or re-engaging users to provision a payment method to the merchant wallet.