Retrieving & Listing Merchants
Overview
In your app, you may choose to list available merchants for users to view, select from, and ultimately authenticate with. Knot allows you to retrieve a list of available merchants based on a number of parameters so that you may list them in your app or even allow users to search through a list of merchants.
This optional functionality serves as an alternative to the merchant list and search experience within the Knot SDK. In addition, choosing to list merchants in your app goes hand-in-hand with providing a specific merchant (that the user selected) when you initialize the SDK.
Retrieving, Listing, and Searching
You can retrieve merchants from the Get Merchants endpoint. In doing so, there are a number of body parameters that will modify the merchant list in the response.
type
typeThe value you provide in this parameter ensures that the merchant list you receive includes available merchants for a specific product. This is important as not all product use cases are supported for every merchant on Knot's platform.
platform
platformKnot supports merchants across iOS, android, and web, however, not every merchant is supported on each. This parameter can be used to retrieve a list of available merchants on a given platform, so that only those available merchants may be displayed to users on each platform.
search
searchIf you choose to offer your users a search experience in your app where they can search for different merchants by keyword, you can provide a user's search keyword to this parameter and retrieve a merchant (or list of merchants) that match that keyword.
For example, if you provide a user's search keyword as hub to this parameter, you may receive a list of merchants including Grubhub, Stubhub, and Github.
Specific Users
external_user_id and status
external_user_id and statusThe Get Merchants endpoint can be used to retrieve a user's status with specific merchants. Providing an external_user_id in the request will add a status field to the list of available merchants already returned from this endpoint. The status represents the status of the user's lifecycle in connecting to a given merchant, across all sessions.
On the flip side, a value for the status parameter can be provided in the request (alongside the external_user_id) to return only a subset of the list of available merchants with that status for a particular user.
Statuses:
status | Description |
|---|---|
not enrolled | The user has not provided login credentials (or other sufficient step-up authentication information such as an OTP code) to authenticate with the merchant. |
enrolling | The user provided login credentials (or other step-up authentication information such as an OTP code) for the merchant and authentication to the merchant is currently taking place. |
credentials | The user attempted to login to the merchant, but provided incorrect login credentials and needs to provide new ones to re-attempt the login. |
otp | The user needs to provide a step-up authentication OTP code to login to the merchant, either for the first time or because it was provided incorrectly before. If the user does not provide this within a short period, the status will change to failed. |
approval | The user needs to approve the login via a push notification, text message, or similar from the merchant. |
questions | The user needs to provide answers to security questions. |
zip | The user needs to provide their zip code. |
enrolled | The user successfully logged in to the merchant and the action (such as a card switch) was performed successfully (if applicable). |
failed | The user was unsuccessful in logging in to the merchant or was successful, but the action (such as a card switch) was unsuccessful (if applicable). |
Specific Sessions
The Get Connected Merchants endpoint can be used to retrieve a merchant list for a particular session_id by providing the session_id in the request. The status field in the response represents the status of the user's lifecycle in connecting to a given merchant, for that specific session. Only merchants in the enrolled or failed status are returned.
Updated 4 months ago