Quickstart
Getting started
Start the flow
Access your customer dashboad
Access your customer dashboad
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 thedevelopment and production environments.
Subscribe to webhooks
Subscribe to webhooks
Subscribe to webhooks in your Customer Dashboard so your backend can be notified about user-generated events, as well as asynchronous processes. You will need to receive these events later on in the flow.
Retrieve available merchants
Retrieve available merchants
Call List Merchants to retrieve a list of merchants that are available for the Shopping product by passing type = shopping. These are merchants you can display in your app, allow users to link, and subsequently shop at. To get started quickly, you can use merchant_id: 45 for Walmart to later pass when initializing the SDK.
You will be notified via the MERCHANT_STATUS_UPDATE webhook when/if this list changes.
Create a session
Create a session
With your client_id and secret for the development environment, call Create Session with type: link to create a session used when invoking the SDK.
Install the SDK
Install the SDK
Install an SDK of your choosing, for example on iOS here. If you are using the Web SDK, make sure to allowlist your application’s domains for the development and production environments in your Customer Dashboard.
Initialize the SDK
Initialize the SDK
Initialize the SDK with the session_id retrieved from Create Session. In KnotConfiguration, pass a merchant Id retrieved from List Merchants or you can use merchant_id: 45 for Walmart to get started quickly. The SDK is where users will interact with the Knot UI to link various merchant accounts. All login flows, including step-up authentication, are handled within the SDK. Users will see real-time feedback as they link a merchant account.
Specifying an exact merchant by passing a merchant Id in KnotConfiguration is required when initializing the SDK with a session with type: link.
Link a merchant account
Login
Login
In the development environment, login to a merchant account using user_good / pass_good credentials to link your user’s merchant account.
Handle authenticated event
Handle authenticated event
Ingest the AUTHENTICATED webhook to notify your backend that the merchant account is successfully linked to Knot and that the connection status is connected. Similarly and as applicable, listen to the client-side onEvent callback in the SDK to receive the authenticated event.
You can also use Get Merchant Accounts to retrieve this and other merchant accounts, as well as their connection status. This can be useful to know that you should display the merchant account to the user in their list of linked merchant accounts with the appropriate connection status (i.e. connected or disconnected). See more about handling disconnected merchant accounts here.
Add a product to a cart
Call Sync Cart to add a product to a cart using the product.external_id. To be notified when a product is successfully added to a cart and to receive cart information, listen to the SYNC_CART_SUCCEEDED webhook.
Update delivery address (optional)
If a user would like to update their delivery address after initially provided in Sync Cart, simply make the same request again with a new delivery_location, like you are patching the cart. You will receive fresh information regarding the cart, including the price.total.
A delivery address must be present in the user’s merchant account prior to checkout if the fulfillment is via any delivery option. Therefore, if a delivery_location is not provided in Sync Cart and/or a delivery_location is not provided back in SYNC_CART_SUCCEEDED, then you cannot proceed with Checkout.
Update fulfillment preference (optional)
If a user would like to update the fulfillment preference for a given product after the initial Sync Cart request, simply make the same request again with a value for products.fulfillment.id that you received in the SYNC_CART_SUCCEEDED webhook. You will receive fresh information regarding the cart, including the price.total.
Checkout
Call Checkout to checkout a cart. To be notified when a checkout process is successful, listen to the CHECKOUT_SUCCEEDED webhook, which will include an array of transactions by Id created by the checkout.
Get order confirmation details
When you receive the CHECKOUT_SUCCEEDED webhook, call Get Transaction By Id for each transaction you receive (using the transaction.id) to retrieve transaction information and subsequently enrich an order confirmation.
Handle disconnected merchant accounts
If for example a user changes their password to a merchant account, the connection.status in Get Merchant Accounts will be returned as disconnected and you will not be able to make any successful requests to Sync Cart or Checkout until the user’s merchant account is reconnected. In this case, you’ll want to display a UX in your app to allow users to reconnect their account. For example, you may choose to display a button that says “Reconnect” or similarly allow the user to invoke the SDK to reconnect their account.