Quickstart - Docs

Introduction

SubscriptionManager allows you to retrieve subscription information from a user’s merchant accounts. There are two ways to retrieve subscriptions depending on your use case:

After provisioning your card to the merchant account with CardSwitcher: the user authenticates to the merchant account, their card is provisioned, and their subscription data is returned in the CARD_UPDATED webhook event.
Without provisioning a card: the user authenticates to the merchant account and their subscription data is returned in the NEW_SUBSCRIPTIONS_AVAILABLE webhook event.

SubscriptionManager must be enabled for your account. Reach out to the Knot team to get started.

Getting Started

CardSwitcher
Without provisioning a card

If you have already integrated CardSwitcher, you can receive subscription data as part of the card switch flow without any additional client-side integration.

Receive Subscription IDs

When a card is successfully updated, the CARD_UPDATED webhook will include subscription IDs in data.subscriptions:

{
  "event": "CARD_UPDATED",
  ...
  "data": {
    "card_id": "123456789",
    "subscriptions": [
      { "id": "ka8sdf0asdfm10as0a0sdfja7ssa8" },
      { "id": "8asdh29qjss923kd0d920skd8sjd8" }
    ]
  }
}

Use this approach when you want to retrieve subscription data without provisioning a card to the user’s merchant account. For example, you may choose this option when the user’s card is already present on the merchant account or you have not issued the user a card at all, but they want to take advantage of subscription management functionality.

Set Up

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.

Install the SDK

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

Subscribe to webhooks

Start the Flow

Retrieve available merchants

Call List Merchants to retrieve a list of merchants that are available for the SubscriptionManager product by passing type = subscription_manager. These are merchants you can display in your app and allow users to link. More here on natively displaying available merchants.You will be notified via the MERCHANT_STATUS_UPDATE webhook when the availability of merchants change by product & platform, so it is not necessary to call List Merchants each time users interact with your app.

Merchant IDs are static and remain constant across all environments.

Call the API to 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. This will allow the user to link their merchant account without provisioning a card.

Initialize the SDK and handle callbacks

Initialize the SDK with the session_id retrieved from Create Session and a merchant Id retrieved from List Merchants in KnotConfiguration. 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.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.

Login

In the development environment, use testing credentials to login to a merchant account and simulate retrieving subscriptions.

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.You can also use Get Merchant Accounts to retrieve this and other merchant accounts, as well as their connection status.

Receive Subscription IDs

After the user authenticates, Knot automatically pulls subscription data from the merchant account. Listen for the NEW_SUBSCRIPTIONS_AVAILABLE webhook to be notified of subscriptions on the merchant account.

{
  "event": "NEW_SUBSCRIPTIONS_AVAILABLE",
  ...
  "data": {
    "subscriptions": [
      { "id": "ka8sdf0asdfm10as0a0sdfja7ssa8" },
      { "id": "8asdh29qjss923kd0d920skd8sjd8" }
    ]
  }
}

Retrieve Full Subscription Details

Upon receiving the webhook, call Get Subscription By ID for each ID in data.subscriptions to retrieve the full subscription object.

Get Ongoing Updates

New subscriptions

To be notified when new subscriptions are detected on a merchant account, listen to the NEW_SUBSCRIPTIONS_AVAILABLE webhook. You will receive this event each time a new subscription is found on the merchant account. Upon receiving the NEW_SUBSCRIPTIONS_AVAILABLE webhook, make a request to Get Subscription By ID for each ID in data.subscriptions, passing the ID received in the webhook as a path parameter.

Updated subscriptions

Receiving updated subscription information is entirely optional and may not be relevant for your use case.

To be notified about updates to existing subscriptions, listen to the UPDATED_SUBSCRIPTIONS_AVAILABLE webhook. You will receive this event for a merchant account each time there are existing subscriptions for which data has changed (e.g. a price change or status update). Upon receiving the UPDATED_SUBSCRIPTIONS_AVAILABLE webhook, make a request to Get Subscription By ID for each ID in data.subscriptions, passing the ID received in the webhook as a path parameter.

Cancel a Subscription

Once a user has linked a merchant account, they can cancel a subscription or bill associated with that merchant account. Follow the steps below to determine whether cancellation is available and to execute it.

Display the subscription in your app

Call Get Merchant Accounts with the user’s external_user_id and merchant_id to check whether cancellation is supported for that merchant account.

curl --request GET \
  --url 'https://development.knotapi.com/accounts/get?external_user_id=15d036d8-0ae5-41bb-84fa-88f839465e5e&merchant_id=45' \
  --header 'Authorization: Basic Y2xpZW50X2lkOnNlY3JldA=='

In the response, check that the merchant account’s connection.scopes array contains an object with "type": "cancel" and that the subscription’s is_cancellable field is true. Only when both conditions are met should you display a cancel button to the user.

// Example connection object from Get Merchant Accounts response
{
  "connection": {
    "status": "connected",
    "scopes": [
      { "type": "update_card" },
      { "type": "cancel" }
    ]
  }
}

Call the Cancel Subscription endpoint

When the user taps the cancel button, call Cancel Subscription with the subscription ID to cancel the subscription or bill within seconds. Subscribe to the CANCELLATION_SUCCEEDED and CANCELLATION_FAILED webhooks to be notified of the outcome.

Handle disconnected merchant accounts

If for example a user changes their password to a merchant account, the Get Merchant Accounts endpoint will connection.status: disconnected and you’ll be notified via the ACCOUNT_LOGIN_REQUIRED webhook event. When this occurs, subscription data will not be refreshed (e.g. in case there is a plan or status change) and you will not be able to make requests to Cancel Subscription without the user relinking their merchant account. 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 “Refresh” depending on the exact UX. When the user clicks the button, call Create Session with type: link and invoke the SDK to allow the user to reconnect their merchant account.

To test this behavior in development, use the Disconnect Account endpoint.

Testing

To test SubscriptionManager in the development environment, use one of the merchants below. The following is a subset of merchants available for testing - it is not the full list of supported merchants.

Verizon
T-Mobile
Spectrum
Xfinity Internet
Xfinity Mobile
Apple
Netflix
Disney+
Hulu
Spotify

Via CardSwitcher: Perform a card switch via CardSwitcher with one of the merchants above. Testing docs here. The resulting CARD_UPDATED webhook will include subscription IDs that you can then use to test retrieval of the full subscription details. Without provisioning a card: Create a session with type: link, initialize the SDK with a test merchant, and authenticate using testing credentials user_good/ pass_good. The NEW_SUBSCRIPTIONS_AVAILABLE webhook will fire and include subscription IDs that you can then use to test retrieval.

​Introduction

​Getting Started

​Receive Subscription IDs

​Set Up

Access your customer dashboard

Install the SDK

Subscribe to webhooks

​Start the Flow

Retrieve available merchants

Call the API to create a session

Initialize the SDK and handle callbacks

Login

Handle authenticated event

​Receive Subscription IDs

​Retrieve Full Subscription Details

​Get Ongoing Updates

​New subscriptions

​Updated subscriptions

​Cancel a Subscription

​Handle disconnected merchant accounts

​Testing

Introduction

Getting Started

Receive Subscription IDs

Set Up

Start the Flow

Receive Subscription IDs

Retrieve Full Subscription Details

Get Ongoing Updates

New subscriptions

Updated subscriptions

Cancel a Subscription

Handle disconnected merchant accounts

Testing